Willkommen bei WordPress. Dies ist dein erster Beitrag. Bearbeite oder lösche ihn und beginne mit dem Schreiben!
Hallo Welt!
von raredesign | Dez 3, 2019 | Allgemein | 0 Kommentare
Cokiee Shell
| Current Path : /proc/self/root/usr/local/share/man/man3/ |
| Current File : //proc/self/root/usr/local/share/man/man3/OldDocs::SOAP::Lite.3pm |
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OldDocs::SOAP::Lite 3pm"
.TH OldDocs::SOAP::Lite 3pm "2004-10-16" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SOAP::Lite \- Client and server side SOAP implementation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\& use SOAP::Lite;
\& print SOAP::Lite
\& \-> uri(\*(Aqhttp://www.soaplite.com/Temperatures\*(Aq)
\& \-> proxy(\*(Aqhttp://services.soaplite.com/temper.cgi\*(Aq)
\& \-> f2c(32)
\& \-> result;
.Ve
.PP
The same code with autodispatch:
.PP
.Vb 3
\& use SOAP::Lite +autodispatch =>
\& uri => \*(Aqhttp://www.soaplite.com/Temperatures\*(Aq,
\& proxy => \*(Aqhttp://services.soaplite.com/temper.cgi\*(Aq;
\&
\& print f2c(32);
.Ve
.PP
Code in OO-style:
.PP
.Vb 3
\& use SOAP::Lite +autodispatch =>
\& uri => \*(Aqhttp://www.soaplite.com/Temperatures\*(Aq,
\& proxy => \*(Aqhttp://services.soaplite.com/temper.cgi\*(Aq;
\&
\& my $temperatures = Temperatures\->new(32); # get object
\& print $temperatures\->as_celsius; # invoke method
.Ve
.PP
Code with service description:
.PP
.Vb 4
\& use SOAP::Lite;
\& print SOAP::Lite
\& \-> service(\*(Aqhttp://www.xmethods.net/sd/StockQuoteService.wsdl\*(Aq)
\& \-> getQuote(\*(AqMSFT\*(Aq);
.Ve
.PP
Code for \s-1SOAP\s0 server (\s-1CGI\s0):
.PP
.Vb 4
\& use SOAP::Transport::HTTP;
\& SOAP::Transport::HTTP::CGI
\& \-> dispatch_to(\*(Aq/Your/Path/To/Deployed/Modules\*(Aq, \*(AqModule::Name\*(Aq, \*(AqModule::method\*(Aq)
\& \-> handle;
.Ve
.PP
Visual Basic client (through \s-1COM\s0 interface):
.PP
.Vb 4
\& MsgBox CreateObject("SOAP.Lite").new( _
\& "proxy", "http://services.xmethods.net/soap", _
\& "uri", "urn:xmethods\-delayed\-quotes" _
\& ).getQuote("MSFT").result
.Ve
.PP
mod_soap enabled \s-1SOAP\s0 server:
.PP
.Vb 1
\& .htaccess
\&
\& SetHandler perl\-script
\& PerlHandler Apache::SOAP
\& PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name"
.Ve
.PP
\&\s-1ASP/VB\s0 \s-1SOAP\s0 server:
.PP
.Vb 8
\& <%
\& Response.ContentType = "text/xml"
\& Response.Write(Server.CreateObject("SOAP.Lite") _
\& .server("SOAP::Server") _
\& .dispatch_to("/Your/Path/To/Deployed/Modules") _
\& .handle(Request.BinaryRead(Request.TotalBytes)) _
\& )
\& %>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
SOAP::Lite is a collection of Perl modules which provides a
simple and lightweight interface to the Simple Object Access Protocol
(\s-1SOAP\s0) both on client and server side.
.PP
This version of SOAP::Lite supports the \s-1SOAP\s0 1.1 specification ( http://www.w3.org/TR/SOAP ).
.PP
The main features of the library are:
.IP "\(bu" 3
Supports \s-1SOAP\s0 1.1 spec.
.IP "\(bu" 3
Interoperability tests with different implementations: Apache \s-1SOAP\s0, Apache Axis, Frontier, Microsoft \s-1SOAP\s0, Microsoft .NET, DevelopMentor, XMethods, 4s4c, Phalanx, PocketSOAP, Kafka, SQLData, Lucin (in Java, Perl, \*(C+, Python, \s-1VB\s0, \s-1COM\s0, \s-1XSLT\s0).
.IP "\(bu" 3
Provides \s-1COM\s0 interface. Single dll (standalone [2.5MB] or minimal [32kB]).
Works on Windows 9x/Me/NT/2K. Doesn't require \s-1ROPE\s0 or \s-1MSXML\s0.
Examples in \s-1VB\s0, Excel/VBA, C#, \s-1ASP\s0, JavaScript, PerlScript and Perl.
.IP "\(bu" 3
Provides transparent compression support for \s-1HTTP\s0 transport.
.IP "\(bu" 3
Provides mod_soap module. Make \s-1SOAP\s0 server with a few lines in .htaccess
or .conf file.
.IP "\(bu" 3
Includes XML::Parser::Lite (regexp-based \s-1XML\s0 parser) which runs instead
of XML::Parser where Perl 5.6 runs (even on WinCE) with some limitations.
.IP "\(bu" 3
Includes XMLRPC::Lite, implementation of XML-RPC protocol on client and
server side. All transports and features of SOAP::Lite are available.
.IP "\(bu" 3
Supports multipart/form\-data \s-1MIME\s0 attachments.
.IP "\(bu" 3
Supports circular linked lists and multiple references.
.IP "\(bu" 3
Supports Map datatype (encoding of maps/hashes with arbitrary keys).
.IP "\(bu" 3
Supports \s-1HTTPS\s0 protocol.
.IP "\(bu" 3
Provides proxy support.
.IP "\(bu" 3
Provides CGI/daemon/mod_perl/Apache::Registry server implementations.
.IP "\(bu" 3
Provides \s-1TCP\s0 server implementation.
.IP "\(bu" 3
Provides \s-1IO\s0 (STDIN/STDOUT/File) server implementation.
.IP "\(bu" 3
Provides \s-1FTP\s0 client implementation.
.IP "\(bu" 3
Supports single/multipart \s-1MIME\s0 attachment (parsing side only).
.IP "\(bu" 3
Supports \s-1SMTP\s0 protocol.
.IP "\(bu" 3
Provides \s-1POP3\s0 server implementation.
.IP "\(bu" 3
Supports M\-POST and redirects in \s-1HTTP\s0 transport.
.IP "\(bu" 3
Supports Basic/Digest server authentication.
.IP "\(bu" 3
Works with \s-1CGI\s0 accelerators, like VelociGen and PerlEx.
.IP "\(bu" 3
Supports \s-1UDDI\s0 interface on client side. See UDDI::Lite for details.
.IP "\(bu" 3
Supports \s-1UDDI\s0 publishing \s-1API\s0. Examples and documentation provided.
.IP "\(bu" 3
Supports \s-1WSDL\s0 schema with stub and run-time access.
.IP "\(bu" 3
Supports blessed object references.
.IP "\(bu" 3
Supports arrays (both serialization and deserialization with autotyping).
.IP "\(bu" 3
Supports custom serialization.
.IP "\(bu" 3
Provides exception transport with custom exceptions
.IP "\(bu" 3
Supports Base64 encoding.
.IP "\(bu" 3
Supports \s-1XML\s0 entity encoding.
.IP "\(bu" 3
Supports header attributes.
.IP "\(bu" 3
Supports dynamic and static class/method binding.
.IP "\(bu" 3
Supports objects-by-reference with simple garbage collection and activation.
.IP "\(bu" 3
Provides shell for interactive \s-1SOAP\s0 sessions.
.IP "\(bu" 3
Supports out parameters binding.
.IP "\(bu" 3
Supports transparent \s-1SOAP\s0 calls with autodispatch feature.
.IP "\(bu" 3
Provides easy services deployment. Put module in specified directory and
it'll be accessible.
.IP "\(bu" 3
Has tests, examples and documentation to let you be up and running in no time.
.SS "\s-1WHERE\s0 \s-1TO\s0 \s-1FIND\s0 \s-1EXAMPLES\s0"
.IX Subsection "WHERE TO FIND EXAMPLES"
See \fIt/*.t\fR, \fIexamples/*.pl\fR and the module documentation for a client-side
examples that demonstrate the serialization of a \s-1SOAP\s0 request, sending it
via \s-1HTTP\s0 to the server and receiving the response, and the deserialization
of the response. See \fIexamples/server/*\fR for server-side implementations.
.SH "OVERVIEW OF CLASSES AND PACKAGES"
.IX Header "OVERVIEW OF CLASSES AND PACKAGES"
This table should give you a quick overview of the classes provided by the
library.
.PP
.Vb 10
\& SOAP::Lite.pm
\& \-\- SOAP::Lite \-\- Main class provides all logic
\& \-\- SOAP::Transport \-\- Supports transport architecture
\& \-\- SOAP::Data \-\- Provides extensions for serialization architecture
\& \-\- SOAP::Header \-\- Provides extensions for header serialization
\& \-\- SOAP::Parser \-\- Parses XML file into object tree
\& \-\- SOAP::Serializer \-\- Serializes data structures to SOAP package
\& \-\- SOAP::Deserializer \-\- Deserializes results of SOAP::Parser into objects
\& \-\- SOAP::SOM \-\- Provides access to deserialized object tree
\& \-\- SOAP::Constants \-\- Provides access to common constants
\& \-\- SOAP::Trace \-\- Provides tracing facilities
\& \-\- SOAP::Schema \-\- Provides access and stub(s) for schema(s)
\& \-\- SOAP::Schema::WSDL \-\- WSDL implementation for SOAP::Schema
\& \-\- SOAP::Server \-\- Handles requests on server side
\& \-\- SOAP::Server::Object \-\- Handles objects\-by\-reference
\& \-\- SOAP::Fault \-\- Provides support for Faults on server side
\& \-\- SOAP::Utils \-\- A set of private and public utility subroutines
\&
\& SOAP::Transport::HTTP.pm
\& \-\- SOAP::Transport::HTTP::Client \-\- Client interface to HTTP transport
\& \-\- SOAP::Transport::HTTP::Server \-\- Server interface to HTTP transport
\& \-\- SOAP::Transport::HTTP::CGI \-\- CGI implementation of server interface
\& \-\- SOAP::Transport::HTTP::Daemon \-\- Daemon implementation of server interface
\& \-\- SOAP::Transport::HTTP::Apache \-\- mod_perl implementation of server interface
\&
\& SOAP::Transport::POP3.pm
\& \-\- SOAP::Transport::POP3::Server \-\- Server interface to POP3 protocol
\&
\& SOAP::Transport::MAILTO.pm
\& \-\- SOAP::Transport::MAILTO::Client \-\- Client interface to SMTP/sendmail
\&
\& SOAP::Transport::LOCAL.pm
\& \-\- SOAP::Transport::LOCAL::Client \-\- Client interface to local transport
\&
\& SOAP::Transport::TCP.pm
\& \-\- SOAP::Transport::TCP::Server \-\- Server interface to TCP protocol
\& \-\- SOAP::Transport::TCP::Client \-\- Client interface to TCP protocol
\&
\& SOAP::Transport::IO.pm
\& \-\- SOAP::Transport::IO::Server \-\- Server interface to IO transport
.Ve
.SS "SOAP::Lite"
.IX Subsection "SOAP::Lite"
All methods that \f(CW\*(C`SOAP::Lite\*(C'\fR provides can be used for both
setting and retrieving values. If you provide no parameters, you will
get current value, and if parameters are provided, a new value
will be assigned to the object and the method in question will return
the current object (if not stated otherwise). This is suitable for stacking
these calls like:
.PP
.Vb 4
\& $lite = SOAP::Lite
\& \-> uri(\*(Aqhttp://simon.fell.com/calc\*(Aq)
\& \-> proxy(\*(Aqhttp://soap.4s4c.com/ssss4c/soap.asp\*(Aq)
\& ;
.Ve
.PP
The order is insignificant and you may call the \fInew()\fR method first. If you
don't do it, SOAP::Lite will do it for you. However, the \fInew()\fR method
gives you an additional syntax:
.PP
.Vb 4
\& $lite = new SOAP::Lite
\& uri => \*(Aqhttp://simon.fell.com/calc\*(Aq,
\& proxy => \*(Aqhttp://soap.4s4c.com/ssss4c/soap.asp\*(Aq
\& ;
.Ve
.IP "\fInew()\fR" 4
.IX Item "new()"
\&\fInew()\fR accepts a hash with method names as keys. It will call the
appropriate methods together with the passed values. Since \fInew()\fR is
optional it won't be mentioned anymore.
.IP "\fItransport()\fR" 4
.IX Item "transport()"
Provides access to the \*(L"SOAP::Transport\*(R" object. The object will be created
for you. You can reassign it (but generally you should not).
.IP "\fIserializer()\fR" 4
.IX Item "serializer()"
Provides access to the \*(L"SOAP::Serializer\*(R" object. The object will be
created for you. You can reassign it (but generally you should not).
.IP "\fIproxy()\fR" 4
.IX Item "proxy()"
Shortcut for \f(CW\*(C`transport\->proxy()\*(C'\fR. This lets you specify an endpoint
(service address) and also loads the required module at the same time. It is
required for dispatching \s-1SOAP\s0 calls. The name of the module will be defined
depending on the protocol specific for the endpoint. The prefix
\&\f(CW\*(C`SOAP::Transport\*(C'\fR will be prepended, the module will be loaded and object of
class (with appended \f(CW\*(C`::Client\*(C'\fR) will be created.
.Sp
For example, for \fIhttp://localhost/\fR, the class for creating objects will
look for \f(CW\*(C`SOAP::Transport:HTTP::Client\*(C'\fR;
.Sp
In addition to endpoint parameter, \fIproxy()\fR can accept any transport specific
parameters that could be passed as name => value pairs. For example, to
specify proxy settings for \s-1HTTP\s0 protocol you may do:
.Sp
.Vb 2
\& $soap\->proxy(\*(Aqhttp://endpoint.server/\*(Aq,
\& proxy => [\*(Aqhttp\*(Aq => \*(Aqhttp://my.proxy.server/\*(Aq]);
.Ve
.Sp
Notice that since proxy (second one) expects to get more than one
parameter you should wrap them in array.
.Sp
Another useful example can be the client that is sensitive to cookie-based
authentication. You can provide this with:
.Sp
.Vb 2
\& $soap\->proxy(\*(Aqhttp://localhost/\*(Aq,
\& cookie_jar => HTTP::Cookies\->new(ignore_discard => 1));
.Ve
.Sp
You may specify timeout for \s-1HTTP\s0 transport with following code:
.Sp
.Vb 1
\& $soap\->proxy(\*(Aqhttp://localhost/\*(Aq, timeout => 5);
.Ve
.IP "\fIendpoint()\fR" 4
.IX Item "endpoint()"
Lets you specify an endpoint \fBwithout\fR changing/loading the protocol module.
This is useful for switching endpoints without switching protocols. You should
call \f(CW\*(C`proxy()\*(C'\fR first. No checks for protocol equivalence will be made.
.IP "\fIoutputxml()\fR" 4
.IX Item "outputxml()"
Lets you specify the kind of output from all method calls. If \f(CW\*(C`true\*(C'\fR, all
methods will return unprocessed, raw \s-1XML\s0 code. You can parse it with
XML::Parser, SOAP::Deserializer or any other appropriate module.
.IP "\fIautotype()\fR" 4
.IX Item "autotype()"
Shortcut for \f(CW\*(C`serializer\->autotype()\*(C'\fR. This lets you specify whether
the serializer will try to make autotyping for you or not. Default setting
is \f(CW\*(C`true\*(C'\fR.
.IP "\fIreadable()\fR" 4
.IX Item "readable()"
Shortcut for \f(CW\*(C`serializer\->readable()\*(C'\fR. This lets you specify the format
for the generated \s-1XML\s0 code. Carriage returns <\s-1CR\s0> and indentation will be
added for readability. Useful in the case you want to see the generated code
in a debugger. By default, there are no additional characters in generated
\&\s-1XML\s0 code.
.IP "\fIuse_prefix()\fR" 4
.IX Item "use_prefix()"
Shortcut for \f(CW\*(C`serializer\->use_prefix()\*(C'\fR. This lets you turn on/off the
use of a namespace prefix for the children of the /Envelope/Body element.
Default is 'true'. (This was introduced in 0.61 for better .NET compatibility)
.Sp
When use_prefix is set to 'true', serialized \s-1XML\s0 will look like this:
.Sp
.Vb 5
\& <SOAP\-ENV:Envelope ...attributes skipped>
\& <SOAP\-ENV:Body>
\& <namesp1:mymethod xmlns:namesp1="urn:MyURI" />
\& </SOAP\-ENV:Body>
\& </SOAP\-ENV:Envelope>
.Ve
.Sp
When use_prefix is set to 'true', serialized \s-1XML\s0 will look like this:
.Sp
.Vb 5
\& <SOAP\-ENV:Envelope ...attributes skipped>
\& <SOAP\-ENV:Body>
\& <mymethod xmlns="urn:MyURI" />
\& </SOAP\-ENV:Body>
\& </SOAP\-ENV:Envelope>
.Ve
.IP "\fInamespace()\fR" 4
.IX Item "namespace()"
Shortcut for \f(CW\*(C`serializer\->namespace()\*(C'\fR. This lets you specify the default
namespace for generated envelopes (\f(CW\*(AqSOAP\-ENV\*(Aq\fR by default).
.IP "\fIencodingspace()\fR" 4
.IX Item "encodingspace()"
Shortcut for \f(CW\*(C`serializer\->encodingspace()\*(C'\fR. This lets you specify the
default encoding namespace for generated envelopes (\f(CW\*(AqSOAP\-ENC\*(Aq\fR by default).
.IP "\fIencoding()\fR" 4
.IX Item "encoding()"
Shortcut for \f(CW\*(C`serializer\->encoding()\*(C'\fR. This lets you specify the encoding
for generated envelopes. It does not actually change envelope
encoding, it will just modify the \s-1XML\s0 declaration (\f(CW\*(AqUTF\-8\*(Aq\fR by default).
Use \f(CW\*(C`undef\*(C'\fR value to \fBnot\fR generate \s-1XML\s0 declaration.
.IP "\fItypelookup()\fR" 4
.IX Item "typelookup()"
Shortcut for \f(CW\*(C`serializer\->typelookup()\*(C'\fR. This gives you access to
the \f(CW\*(C`typelookup\*(C'\fR table that is used for autotyping. For more information
see \*(L"SOAP::Serializer\*(R".
.IP "\fIuri()\fR" 4
.IX Item "uri()"
Shortcut for \f(CW\*(C`serializer\->uri()\*(C'\fR. This lets you specify the uri for \s-1SOAP\s0
methods. Nothing is specified by default and your call will definitely fail
if you don't specify the required uri.
.Sp
\&\fB\s-1WARNING\s0\fR: URIs are just identifiers. They may \fBlook like URLs\fR, but they are
not guaranteed to point to anywhere and shouldn't be used as such pointers.
URIs assume to be unique within the space of all \s-1XML\s0 documents, so consider
them as unique identifiers and nothing else.
.IP "\fImultirefinplace()\fR" 4
.IX Item "multirefinplace()"
Shortcut for \f(CW\*(C`serializer\->multirefinplace()\*(C'\fR. If true, the serializer will
put values for multireferences in the first occurrence of the reference.
Otherwise it will be encoded as top independent element, right after \f(CW\*(C`method\*(C'\fR
element inside \f(CW\*(C`Body\*(C'\fR. Default value is \f(CW\*(C`false\*(C'\fR.
.IP "\fIheader()\fR" 4
.IX Item "header()"
\&\fB\s-1DEPRECATED\s0\fR: Use SOAP::Header instead.
.Sp
Shortcut for \f(CW\*(C`serializer\->header()\*(C'\fR. This lets you specify the header for
generated envelopes. You can specify \f(CW\*(C`root\*(C'\fR, \f(CW\*(C`mustUnderstand\*(C'\fR or any
other header using \*(L"SOAP::Data\*(R" class:
.Sp
.Vb 4
\& $serializer = SOAP::Serializer\->envelope(\*(Aqmethod\*(Aq => \*(Aqmymethod\*(Aq, 1,
\& SOAP::Header\->name(t1 => 5)\->mustUnderstand(1),
\& SOAP::Header\->name(t2 => 7)\->mustUnderstand(2),
\& );
.Ve
.Sp
will be serialized into:
.Sp
.Vb 11
\& <SOAP\-ENV:Envelope ...attributes skipped>
\& <SOAP\-ENV:Header>
\& <t1 xsi:type="xsd:int" SOAP\-ENV:mustUnderstand="1">5</t1>
\& <t2 xsi:type="xsd:int" SOAP\-ENV:mustUnderstand="1">7</t2>
\& </SOAP\-ENV:Header>
\& <SOAP\-ENV:Body>
\& <namesp1:mymethod xmlns:namesp1="urn:SOAP_\|_Serializer">
\& <c\-gensym6 xsi:type="xsd:int">1</c\-gensym6>
\& </namesp1:mymethod>
\& </SOAP\-ENV:Body>
\& </SOAP\-ENV:Envelope>
.Ve
.Sp
You can mix \f(CW\*(C`SOAP::Header\*(C'\fR parameters with other parameters and you can also
return \f(CW\*(C`SOAP::Header\*(C'\fR parameters as a result of a remote call. They will be
placed into the header. See \f(CW\*(C`My::Parameters::addheader\*(C'\fR as an example.
.IP "\fIon_action()\fR" 4
.IX Item "on_action()"
This lets you specify a handler for \f(CW\*(C`on_action event\*(C'\fR. It is triggered when
creating SOAPAction. The default handler will set SOAPAction to
\&\f(CW"uri#method"\fR. You can change this behavior globally
(see \*(L"\s-1DEFAULT\s0 \s-1SETTINGS\s0\*(R") or locally, for a particular object.
.IP "\fIon_fault()\fR" 4
.IX Item "on_fault()"
This lets you specify a handler for \f(CW\*(C`on_fault\*(C'\fR event. The default behavior is
to \fBdie\fR on an transport error and to \fBdo nothing\fR on other error conditions. You
may change this behavior globally (see \*(L"\s-1DEFAULT\s0 \s-1SETTINGS\s0\*(R") or locally, for a
particular object.
.IP "\fIon_debug()\fR" 4
.IX Item "on_debug()"
This lets you specify a handler for \f(CW\*(C`on_debug event\*(C'\fR. Default behavior is to
do nothing. Use \f(CW\*(C`+trace/+debug\*(C'\fR option for SOAP::Lite instead. If you use if
be warned that since this method is just interface to \f(CW\*(C`+trace/+debug\*(C'\fR it has
\&\fBglobal\fR effect, so if you install it for one object it'll be in effect for
all subsequent calls (even for other objects).
.Sp
See also: SOAP::Trace;
.IP "\fIon_nonserialized()\fR" 4
.IX Item "on_nonserialized()"
This lets you specify a handler for \f(CW\*(C`on_nonserialized event\*(C'\fR. The default
behavior is to produce a warning if warnings are on for everything that cannot
be properly serialized (like \s-1CODE\s0 references or GLOBs).
.IP "\fIcall()\fR" 4
.IX Item "call()"
Provides alternative interface for remote method calls. You can always
run \f(CW\*(C`SOAP::Lite\->new(...)\->method(@parameters)\*(C'\fR, but \fIcall()\fR gives
you several additional options:
.RS 4
.IP "prefixed method" 4
.IX Item "prefixed method"
If you want to specify prefix for generated method's element one of the
available options is do it with \fIcall()\fR interface:
.Sp
.Vb 4
\& print SOAP::Lite
\& \-> new(....)
\& \-> call(\*(Aqmyprefix:method\*(Aq => @parameters)
\& \-> result;
.Ve
.Sp
This example will work on client side only. If you want to change prefix
on server side you should override default serializer. See
\&\fIexamples/server/soap.*\fR for examples.
.IP "access to any method" 4
.IX Item "access to any method"
If for some reason you want to get access to remote procedures that have
the same name as methods of SOAP::Lite object these calls (obviously) won't
be dispatched. In that case you can originate your call trough \fIcall()\fR:
.Sp
.Vb 4
\& print SOAP::Lite
\& \-> new(....)
\& \-> call(new => @parameters)
\& \-> result;
.Ve
.IP "implementation of \s-1OO\s0 interface" 4
.IX Item "implementation of OO interface"
With autodispatch you can make \s-1CLASS/OBJECT\s0 calls like:
.Sp
.Vb 2
\& my $obj = CLASS\->new(@parameters);
\& print $obj\->method;
.Ve
.Sp
However, because of side effects autodispatch
has, it's not always possible to use this syntax. \fIcall()\fR provides you with
alternative:
.Sp
.Vb 5
\& # you should specify uri()
\& my $soap = SOAP::Lite
\& \-> uri(\*(Aqhttp://my.own.site/CLASS\*(Aq) # <<< CLASS goes here
\& # ..... other parameters
\& ;
\&
\& my $obj = $soap\->call(new => @parameters)\->result;
\& print $soap\->call(method => $obj)\->result;
\& # $obj object will be updated here if necessary,
\& # as if you call $obj\->method() and method() updates $obj
\&
\& # Update of modified object MAY not work if server on another side
\& # is not SOAP::Lite
.Ve
.IP "ability to set method's attributes" 4
.IX Item "ability to set method's attributes"
Additionally this syntax lets you specify attributes for method element:
.Sp
.Vb 5
\& print SOAP::Lite
\& \-> new(....)
\& \-> call(SOAP::Data\->name(\*(Aqmethod\*(Aq)\->attr({xmlns => \*(Aqmynamespace\*(Aq})
\& => @parameters)
\& \-> result;
.Ve
.Sp
You can specify \fBany\fR attibutes and \f(CW\*(C`name\*(C'\fR of \f(CW\*(C`SOAP::Data\*(C'\fR element becomes
name of method. Everything else except attributes is ignored and parameters
should be provided as usual.
.Sp
Be warned, that though you have more control using this method, you \fBshould\fR
specify namespace attribute for method explicitely, even if you made \fIuri()\fR
call earlier. So, if you have to have namespace on method element, instead of:
.Sp
.Vb 5
\& print SOAP::Lite
\& \-> new(....)
\& \-> uri(\*(Aqmynamespace\*(Aq) # will be ignored
\& \-> call(SOAP::Data\->name(\*(Aqmethod\*(Aq) => @parameters)
\& \-> result;
.Ve
.Sp
do
.Sp
.Vb 5
\& print SOAP::Lite
\& \-> new(....)
\& \-> call(SOAP::Data\->name(\*(Aqmethod\*(Aq)\->attr({xmlns => \*(Aqmynamespace\*(Aq})
\& => @parameters)
\& \-> result;
.Ve
.Sp
because in the former call \fIuri()\fR will be ignored and namespace won't be
specified. If you run script with \f(CW\*(C`\-w\*(C'\fR option (as recommended) SOAP::Lite
gives you a warning:
.Sp
.Vb 1
\& URI is not provided as attribute for method (method)
.Ve
.Sp
Moreover, it'll become fatal error if you try to call it with prefixed name:
.Sp
.Vb 5
\& print SOAP::Lite
\& \-> new(....)
\& \-> uri(\*(Aqmynamespace\*(Aq) # will be ignored
\& \-> call(SOAP::Data\->name(\*(Aqa:method\*(Aq) => @parameters)
\& \-> result;
.Ve
.Sp
gives you:
.Sp
.Vb 1
\& Can\*(Aqt find namespace for method (a:method)
.Ve
.Sp
because nothing is associated with prefix \f(CW\*(Aqa\*(Aq\fR.
.RE
.RS 4
.Sp
One more comment. One case when SOAP::Lite will change something that
you specified is when you specified prefixed name and empty namespace name:
.Sp
.Vb 5
\& print SOAP::Lite
\& \-> new(....)
\& \-> uri(\*(Aq\*(Aq)
\& \-> call(\*(Aqa:method\*(Aq => @parameters)
\& \-> result;
.Ve
.Sp
This code will generate:
.Sp
.Vb 1
\& <method xmlns="">....</method>
.Ve
.Sp
instead of
.Sp
.Vb 1
\& <a:method xmlns:a="">....</method>
.Ve
.Sp
because later is not allowed according to \s-1XML\s0 Namespace specification.
.Sp
In all other aspects \f(CW\*(C`\->call(mymethod => @parameters)\*(C'\fR is just a
synonim for \f(CW\*(C`\->mymethod(@parameters)\*(C'\fR.
.RE
.IP "\fIself()\fR" 4
.IX Item "self()"
Returns object reference to \fBglobal\fR defaul object specified with
\&\f(CW\*(C`use SOAP::Lite ...\*(C'\fR interface. Both class method and object method return
reference to \fBglobal\fR object, so:
.Sp
.Vb 3
\& use SOAP::Lite
\& proxy => \*(Aqhttp://my.global.server\*(Aq
\& ;
\&
\& my $soap = SOAP::Lite\->proxy(\*(Aqhttp://my.local.server\*(Aq);
\&
\& print $soap\->self\->proxy;
.Ve
.Sp
prints \f(CW\*(Aqhttp://my.global.server\*(Aq\fR (the same as \f(CW\*(C`SOAP::Lite\->self\->proxy\*(C'\fR).
See \*(L"\s-1DEFAULT\s0 \s-1SETTINGS\s0\*(R" for more information.
.IP "\fIdispatch_from()\fR" 4
.IX Item "dispatch_from()"
Does exactly the same as autodispatch
does, but doesn't install \s-1UNIVERSAL::AUTOLOAD\s0 handler and only install
\&\s-1AUTOLOAD\s0 handlers in specified classes. Can be used only with \f(CW\*(C`use SOAP::Lite ...\*(C'\fR
clause and should be specified first:
.Sp
.Vb 5
\& use SOAP::Lite
\& dispatch_from => [\*(AqA\*(Aq, \*(AqB\*(Aq], # use "dispatch_from => \*(AqA\*(Aq" for one class
\& uri => ....,
\& proxy => ....,
\& ;
\&
\& A\->a;
\& B\->b;
.Ve
.SS "SOAP::Header"
.IX Subsection "SOAP::Header"
The SOAP::Header class is a subclass of the \*(L"SOAP::Data\*(R" class. It is used
in the same way as a SOAP::Data object, however SOAP::Lite will serialize
objects of this type into the \s-1SOAP\s0 Envelope's Header block.
.SS "SOAP::Data"
.IX Subsection "SOAP::Data"
You can use this class if you want to specify a value, a name, atype, a uri or
attributes for \s-1SOAP\s0 elements (use \f(CW\*(C`value()\*(C'\fR, \f(CW\*(C`name()\*(C'\fR, \f(CW\*(C`type()\*(C'\fR,
\&\f(CW\*(C`uri()\*(C'\fR and \f(CW\*(C`attr()\*(C'\fR methods correspondingly).
For example, \f(CW\*(C`SOAP::Data\->name(\*(Aqabc\*(Aq)\->value(123)\*(C'\fR will be serialized
into \f(CW\*(C`<abc>123</abc>\*(C'\fR, as well as will \f(CW\*(C`SOAP::Data\->name(abc => 123)\*(C'\fR.
Each of them (except the \fIvalue()\fR method) can accept a value as the second
parameter. All methods return the current value if you call them without
parameters. The return the object otherwise, so you can stack them. See tests
for more examples. You can import these methods with:
.PP
.Vb 1
\& SOAP::Data\->import(\*(Aqname\*(Aq);
.Ve
.PP
or
.PP
.Vb 1
\& import SOAP::Data \*(Aqname\*(Aq;
.Ve
.PP
and then use \f(CW\*(C`name(abc => 123)\*(C'\fR for brevity.
.PP
An interface for specific attributes is also provided. You can use the \f(CW\*(C`actor()\*(C'\fR,
\&\f(CW\*(C`mustUnderstand()\*(C'\fR, \f(CW\*(C`encodingStyle()\*(C'\fR and \f(CW\*(C`root()\*(C'\fR methods to set/get
values of the correspondent attributes.
.PP
.Vb 3
\& SOAP::Data
\& \->name(c => 3)
\& \->encodingStyle(\*(Aqhttp://xml.apache.org/xml\-soap/literalxml\*(Aq)
.Ve
.PP
will be serialized into:
.PP
.Vb 2
\& <c SOAP\-ENV:encodingStyle="http://xml.apache.org/xml\-soap/literalxml"
\& xsi:type="xsd:int">3</c>
.Ve
.SS "SOAP::Serializer"
.IX Subsection "SOAP::Serializer"
Usually you don't need to interact directly with this module. The only
case when you need it, it when using autotyping. This feature lets you specify
types for your data according to your needs as well as to introduce new
data types (like ordered hash for example).
.PP
You can specify a type with \f(CW\*(C`SOAP::Data\->type(float => 123)\*(C'\fR. During
the serialization stage the module will try to serialize your data with the
\&\f(CW\*(C`as_float\*(C'\fR method. It then calls the \f(CW\*(C`typecast\*(C'\fR method (you can override it
or inherit your own class from \*(L"SOAP::Data\*(R") and only then it will try to
serialize it according to data type (\f(CW\*(C`SCALAR\*(C'\fR, \f(CW\*(C`ARRAY\*(C'\fR or \f(CW\*(C`HASH\*(C'\fR). For example:
.PP
.Vb 1
\& SOAP::Data\->type(\*(Aqordered_hash\*(Aq => [a => 1, b => 2])
.Ve
.PP
will be serialized as an ordered hash, using the \f(CW\*(C`as_ordered_hash\*(C'\fR method.
.PP
If you do not specify a type directly, the serialization module will try
to autodefine the type for you according to the \f(CW\*(C`typelookup\*(C'\fR hash. It contains
the type name as key and the following 3\-element array as value:
.PP
.Vb 3
\& priority,
\& check_function (CODE reference),
\& typecast function (METHOD name or CODE reference)
.Ve
.PP
For example, if you want to add \f(CW\*(C`uriReference\*(C'\fR to autodefined types,
you should add something like this:
.PP
.Vb 2
\& $s\->typelookup\->{uriReference} =
\& [11, sub { $_[0] =~ m!^http://! }, \*(Aqas_uriReference\*(Aq];
.Ve
.PP
and add the \f(CW\*(C`as_uriReference\*(C'\fR method to the \*(L"SOAP::Serializer\*(R" class:
.PP
.Vb 5
\& sub SOAP::Serializer::as_uriReference {
\& my $self = shift;
\& my($value, $name, $type, $attr) = @_;
\& return [$name, {\*(Aqxsi:type\*(Aq => \*(Aqxsd:uriReference\*(Aq, %$attr}, $value];
\& }
.Ve
.PP
The specified methods will work for both autotyping and direct typing, so you
can use either
.PP
.Vb 1
\& SOAP::Data\->type(uriReference => \*(Aqhttp://yahoo.com\*(Aq)>
.Ve
.PP
or just
.PP
.Vb 1
\& \*(Aqhttp://yahoo.com\*(Aq
.Ve
.PP
and it will be serialized into the same type. For more examples see \f(CW\*(C`as_*\*(C'\fR
methods in \*(L"SOAP::Serializer\*(R".
.PP
The SOAP::Serializer provides you with \f(CW\*(C`autotype()\*(C'\fR, \f(CW\*(C`readable()\*(C'\fR, \f(CW\*(C`namespace()\*(C'\fR,
\&\f(CW\*(C`encodingspace()\*(C'\fR, \f(CW\*(C`encoding()\*(C'\fR, \f(CW\*(C`typelookup()\*(C'\fR, \f(CW\*(C`uri()\*(C'\fR, \f(CW\*(C`multirefinplace()\*(C'\fR and
\&\f(CW\*(C`envelope()\*(C'\fR methods. All methods (except \f(CW\*(C`envelope()\*(C'\fR) are described in the
\&\*(L"SOAP::Lite\*(R" section.
.IP "\fIenvelope()\fR" 4
.IX Item "envelope()"
This method allows you to build three kind of envelopes depending on the first
parameter:
.RS 4
.IP "method" 4
.IX Item "method"
.Vb 1
\& envelope(method => \*(Aqmethodname\*(Aq, @parameters);
.Ve
.Sp
or
.Sp
.Vb 1
\& method(\*(Aqmethodname\*(Aq, @parameters);
.Ve
.Sp
Lets you build a request/response envelope.
.IP "fault" 4
.IX Item "fault"
.Vb 1
\& envelope(fault => \*(Aqfaultcode\*(Aq, \*(Aqfaultstring\*(Aq, $details);
.Ve
.Sp
or
.Sp
.Vb 1
\& fault(\*(Aqfaultcode\*(Aq, \*(Aqfaultstring\*(Aq, $details);
.Ve
.Sp
Lets you build a fault envelope. Faultcode will be properly qualified and
details could be string or object.
.IP "freeform" 4
.IX Item "freeform"
.Vb 1
\& envelope(freeform => \*(Aqsomething that I want to serialize\*(Aq);
.Ve
.Sp
or
.Sp
.Vb 1
\& freeform(\*(Aqsomething that I want to serialize\*(Aq);
.Ve
.Sp
Reserved for nonRPC calls. Lets you build your own payload inside a \s-1SOAP\s0
envelope. All \s-1SOAP\s0 1.1 specification rules are enforced, except method
specific ones. See UDDI::Lite as example.
.IP "register_ns" 4
.IX Item "register_ns"
The register_ns subroutine allows users to register a global namespace
with the \s-1SOAP\s0 Envelope. The first parameter is the namespace, the second
parameter to this subroutine is an optional prefix. If a prefix is not
provided, one will be generated automatically for you. All namespaces
registered with the serializer get declared in the <soap:Envelope />
element.
.IP "find_prefix" 4
.IX Item "find_prefix"
The find_prefix subroutine takes a namespace as a parameter and returns
the assigned prefix to that namespace. This eliminates the need to declare
and redeclare namespaces within an envelope. This subroutine is especially
helpful in determining the proper prefix when assigning a type to a
SOAP::Data element. A good example of how this might be used is as follows:
.Sp
SOAP::Data\->name(\*(L"foo\*(R" => \f(CW$inputParams\fR{'foo'})
\->type($client\->serializer\->find_prefix('urn:Foo').':Foo');
.IP "xmlschema" 4
.IX Item "xmlschema"
The xmlschema subroutine tells SOAP::Lite what \s-1XML\s0 Schema to use when
serializing \s-1XML\s0 element values. There are two supported schemas of
SOAP::Lite, they are:
.Sp
.Vb 2
\& http://www.w3.org/1999/XMLSchema, and
\& http://www.w3.org/2001/XMLSchema (default)
.Ve
.RE
.RS 4
.RE
.PP
For more examples see tests and SOAP::Transport::HTTP.pm
.SS "\s-1SOAP::SOM\s0"
.IX Subsection "SOAP::SOM"
All calls you are making through object oriented interface will
return \s-1SOAP::SOM\s0 object, and you can access actual values with it.
Next example gives you brief overview of the class:
.PP
.Vb 2
\& my $soap = SOAP::Lite .....;
\& my $som = $soap\->method(@parameters);
\&
\& if ($som\->fault) { # will be defined if Fault element is in the message
\& print $som\->faultdetail; # returns value of \*(Aqdetail\*(Aq element as
\& # string or object
\& $som\->faultcode; #
\& $som\->faultstring; # also available
\& $som\->faultactor; #
\& } else {
\& $som\->result; # gives you access to result of call
\& # it could be any data structure, for example reference
\& # to array if server didi something like: return [1,2];
\&
\& $som\->paramsout; # gives you access to out parameters if any
\& # for example, you\*(Aqll get array (1,2) if
\& # server returns ([1,2], 1, 2);
\& # [1,2] will be returned as $som\->result
\& # and $som\->paramsall will return ([1,2], 1, 2)
\& # see section IN/OUT, OUT PARAMETERS AND AUTOBINDING
\& # for more information
\&
\& $som\->paramsall; # gives access to result AND out parameters (if any)
\& # and returns them as one array
\&
\& $som\->valueof(\*(Aq//myelement\*(Aq); # returns value(s) (as perl data) of
\& # \*(Aqmyelement\*(Aq if any. All elements in array
\& # context and only first one in scalar
\&
\& $h = $som\->headerof(\*(Aq//myheader\*(Aq); # returns element as SOAP::Header, so
\& # you can access attributes and values
\& # with $h\->mustUnderstand, $h\->actor
\& # or $h\->attr (for all attributes)
\& }
.Ve
.PP
\&\s-1SOAP::SOM\s0 object gives you access to the deserialized envelope via several
methods. All methods accept a node path (similar to XPath notations).
\&\s-1SOM\s0 interprets '/' as the root node, '//' as relative location path
('//Body' will find all bodies in document, as well as
\&'/Envelope//nums' will find all 'nums' nodes under Envelope node),
\&'[num]' as node number and '[op num]' with \f(CW\*(C`op\*(C'\fR being a comparison
operator ('<', '>', '<=', '>=', '!', '=').
.PP
All nodes in nodeset will be returned in document order.
.IP "\fImatch()\fR" 4
.IX Item "match()"
Accepts a path to a node and returns true/false in a boolean context and
a \s-1SOM\s0 object otherwise. \f(CW\*(C`valueof()\*(C'\fR and \f(CW\*(C`dataof()\*(C'\fR can be used to get
value(s) of matched node(s).
.IP "\fIvalueof()\fR" 4
.IX Item "valueof()"
Returns the value of a (previously) matched node. It accepts a node path.
In this case, it returns the value of matched node, but does not change the current
node. Suitable when you want to match a node and then navigate through
node children:
.Sp
.Vb 3
\& $som\->match(\*(Aq/Envelope/Body/[1]\*(Aq); # match method
\& $som\->valueof(\*(Aq[1]\*(Aq); # result
\& $som\->valueof(\*(Aq[2]\*(Aq); # first out parameter (if present)
.Ve
.Sp
The returned value depends on the context. In a scalar context it will return
the first element from matched nodeset. In an array context it will return
all matched elements.
.IP "\fIdataof()\fR" 4
.IX Item "dataof()"
Same as \f(CW\*(C`valueof()\*(C'\fR, but it returns a \*(L"SOAP::Data\*(R" object, so you can get
access to the name, the type and attributes of an element.
.IP "\fIheaderof()\fR" 4
.IX Item "headerof()"
Same as \f(CW\*(C`dataof()\*(C'\fR, but it returns \*(L"SOAP::Header\*(R" object, so you can get
access to the name, the type and attributes of an element. Can be used for
modifying headers (if you want to see updated header inside Header element,
it's better to use this method instead of \f(CW\*(C`dataof()\*(C'\fR method).
.IP "\fInamespaceuriof()\fR" 4
.IX Item "namespaceuriof()"
Returns the uri associated with the matched element. This uri can also be
inherited, for example, if you have
.Sp
.Vb 5
\& <a xmlns=\*(Aqhttp://my.namespace\*(Aq>
\& <b>
\& value
\& </b>
\& </a>
.Ve
.Sp
this method will return same value for 'b' element as for 'a'.
.PP
\&\s-1SOAP::SOM\s0 also provides methods for direct access to the envelope, the body,
methods and parameters (both in and out). All these methods return real
values (in most cases it will be a hash reference), if called as object
method. Returned values also depend on context: in an array context it will
return an array of values and in scalar context it will return the first
element. So, if you want to access the first output parameter, you can call
\&\f(CW\*(C`$param = $som\->paramsout\*(C'\fR;
and you will get it regardless of the actual number of output parameters.
If you call it as class function (for example, SOAP::SOM::method)
it returns an XPath string that matches the current element
('/Envelope/Body/[1]' in case of 'method'). The method will return \f(CW\*(C`undef\*(C'\fR
if not present \s-1OR\s0 if you try to access an undefined element. To distinguish
between these two cases you can first access the \f(CW\*(C`match()\*(C'\fR method that
will return true/false in a boolean context and then get the real value:
.PP
.Vb 5
\& if ($som\->match(\*(Aq//myparameter\*(Aq)) {
\& $value = $som\->valueof; # can be undef too
\& } else {
\& # doesn\*(Aqt exist
\& }
.Ve
.IP "\fIroot()\fR" 4
.IX Item "root()"
Returns the value (as hash) of the root element. Do exactly the same as
\&\f(CW\*(C`$som\->valueof(\*(Aq/\*(Aq)\*(C'\fR does.
.IP "\fIenvelope()\fR" 4
.IX Item "envelope()"
Returns the value (as hash) of the \f(CW\*(C`Envelope\*(C'\fR element. Keys in this hash will be
\&'Header' (if present), 'Body' and any other (optional) elements. Values will
be the deserialized header, body, and elements, respectively.
If called as function (\f(CW\*(C`SOAP::SOM::envelope\*(C'\fR) it will return a Xpath string
that matches the envelope content. Useful when you want just match it and
then iterate over the content by yourself. Example:
.Sp
.Vb 6
\& if ($som\->match(SOAP::SOM::envelope)) {
\& $som\->valueof(\*(AqHeader\*(Aq); # should give access to header if present
\& $som\->valueof(\*(AqBody\*(Aq); # should give access to body
\& } else {
\& # hm, are we doing SOAP or what?
\& }
.Ve
.IP "\fIheader()\fR" 4
.IX Item "header()"
Returns the value (as hash) of the \f(CW\*(C`Header\*(C'\fR element. If you want to access all
attributes in the header use:
.Sp
.Vb 4
\& # get element as SOAP::Data object
\& $transaction = $som\->match(join \*(Aq/\*(Aq, SOAP::SOM::header, \*(Aqtransaction\*(Aq)\->dataof;
\& # then you can access all attributes of \*(Aqtransaction\*(Aq element
\& $transaction\->attr;
.Ve
.IP "\fIheaders()\fR" 4
.IX Item "headers()"
Returns a node set of values with deserialized headers. The difference between
the \f(CW\*(C`header()\*(C'\fR and \f(CW\*(C`headers()\*(C'\fR methods is that the first gives you access
to the whole header and second to the headers inside the 'Header' tag:
.Sp
.Vb 2
\& $som\->headerof(join \*(Aq/\*(Aq, SOAP::SOM::header, \*(Aq[1]\*(Aq);
\& # gives you first header as SOAP::Header object
\&
\& ($som\->headers)[0];
\& # gives you value of the first header, same as
\& $som\->valueof(join \*(Aq/\*(Aq, SOAP::SOM::header, \*(Aq[1]\*(Aq);
\&
\& $som\->header\->{name_of_your_header_here}
\& # gives you value of name_of_your_header_here
.Ve
.IP "\fIbody()\fR" 4
.IX Item "body()"
Returns the value (as hash) of the \f(CW\*(C`Body\*(C'\fR element.
.IP "\fIfault()\fR" 4
.IX Item "fault()"
Returns the value (as hash) of \f(CW\*(C`Fault\*(C'\fR element: \f(CW\*(C`faultcode\*(C'\fR, \f(CW\*(C`faultstring\*(C'\fR and
\&\f(CW\*(C`detail\*(C'\fR. If \f(CW\*(C`Fault\*(C'\fR element is present, \f(CW\*(C`result()\*(C'\fR, \f(CW\*(C`paramsin()\*(C'\fR,
\&\f(CW\*(C`paramsout()\*(C'\fR and \f(CW\*(C`method()\*(C'\fR will return an undef.
.IP "\fIfaultcode()\fR" 4
.IX Item "faultcode()"
Returns the value of the \f(CW\*(C`faultcode\*(C'\fR element if present and undef otherwise.
.IP "\fIfaultstring()\fR" 4
.IX Item "faultstring()"
Returns the value of the \f(CW\*(C`faultstring\*(C'\fR element if present and undef otherwise.
.IP "\fIfaultactor()\fR" 4
.IX Item "faultactor()"
Returns the value of the \f(CW\*(C`faultactor\*(C'\fR element if present and undef otherwise.
.IP "\fIfaultdetail()\fR" 4
.IX Item "faultdetail()"
Returns the value of the \f(CW\*(C`detail\*(C'\fR element if present and undef otherwise.
.IP "\fImethod()\fR" 4
.IX Item "method()"
Returns the value of the method element (all input parameters if you call it on
a deserialized request envelope, and result/output parameters if you call it
on a deserialized response envelope). Returns undef if the 'Fault' element is
present.
.IP "\fIresult()\fR" 4
.IX Item "result()"
Returns the value of the \f(CW\*(C`result\*(C'\fR of the method call. In fact, it will return
the first child element (in document order) of the method element.
.IP "\fIparamsin()\fR" 4
.IX Item "paramsin()"
Returns the value(s) of all passed parameters.
.IP "\fIparamsout()\fR" 4
.IX Item "paramsout()"
Returns value(s) of the output parameters.
.IP "\fIparamsall()\fR" 4
.IX Item "paramsall()"
Returns value(s) of the result \s-1AND\s0 output parameters as one array.
.IP "\fIparts()\fR" 4
.IX Item "parts()"
Return an array of MIME::Entities if the current payload contains attachments, or returns undefined if payload is not \s-1MIME\s0 multipart.
.IP "\fIis_multipart()\fR" 4
.IX Item "is_multipart()"
Returns true if payload is \s-1MIME\s0 multipart, false otherwise.
.SS "SOAP::Schema"
.IX Subsection "SOAP::Schema"
SOAP::Schema gives you ability to load schemas and create stubs according
to these schemas. Different syntaxes are provided:
.IP "\(bu" 4
.Sp
.Vb 6
\& use SOAP::Lite
\& service => \*(Aqhttp://www.xmethods.net/sd/StockQuoteService.wsdl\*(Aq,
\& # service => \*(Aqfile:/your/local/path/StockQuoteService.wsdl\*(Aq,
\& # service => \*(Aqfile:./StockQuoteService.wsdl\*(Aq,
\& ;
\& print getQuote(\*(AqMSFT\*(Aq), "\en";
.Ve
.IP "\(bu" 4
.Sp
.Vb 4
\& use SOAP::Lite;
\& print SOAP::Lite
\& \-> service(\*(Aqhttp://www.xmethods.net/sd/StockQuoteService.wsdl\*(Aq)
\& \-> getQuote(\*(AqMSFT\*(Aq), "\en";
.Ve
.IP "\(bu" 4
.Sp
.Vb 4
\& use SOAP::Lite;
\& my $service = SOAP::Lite
\& \-> service(\*(Aqhttp://www.xmethods.net/sd/StockQuoteService.wsdl\*(Aq);
\& print $service\->getQuote(\*(AqMSFT\*(Aq), "\en";
.Ve
.PP
You can create stub with \fBstubmaker\fR script:
.PP
.Vb 1
\& perl stubmaker.pl http://www.xmethods.net/sd/StockQuoteService.wsdl
.Ve
.PP
and you'll be able to access \s-1SOAP\s0 services in one line:
.PP
.Vb 1
\& perl "\-MStockQuoteService qw(:all)" \-le "print getQuote(\*(AqMSFT\*(Aq)"
.Ve
.PP
or dynamically:
.PP
.Vb 1
\& perl "\-MSOAP::Lite service=>\*(Aqfile:./quote.wsdl\*(Aq" \-le "print getQuote(\*(AqMSFT\*(Aq)"
.Ve
.PP
Other supported syntaxes with stub(s) are:
.IP "\(bu" 4
.Sp
.Vb 2
\& use StockQuoteService \*(Aq:all\*(Aq;
\& print getQuote(\*(AqMSFT\*(Aq), "\en";
.Ve
.IP "\(bu" 4
.Sp
.Vb 2
\& use StockQuoteService;
\& print StockQuoteService\->getQuote(\*(AqMSFT\*(Aq), "\en";
.Ve
.IP "\(bu" 4
.Sp
.Vb 3
\& use StockQuoteService;
\& my $service = StockQuoteService\->new;
\& print $service\->getQuote(\*(AqMSFT\*(Aq), "\en";
.Ve
.PP
Support for schemas is limited for now. Though module was tested with dozen
different schemas it won't understand complex objects and will work only
with \s-1WSDL\s0.
.SS "SOAP::Trace"
.IX Subsection "SOAP::Trace"
SOAP::Trace provides you with a trace/debug facility for the SOAP::Lite
library. To activate it you need to specify a list of traceable
events/parts of SOAP::Lite:
.PP
.Vb 2
\& use SOAP::Lite +trace =>
\& [qw(list of available traces here)];
.Ve
.PP
Available events are:
.PP
.Vb 11
\& transport \-\- (client) access to request/response for transport layer
\& dispatch \-\- (server) shows full name of dispatched call
\& result \-\- (server) result of method call
\& parameters \-\- (server) parameters for method call
\& headers \-\- (server) headers of received message
\& objects \-\- (both) new/DESTROY calls
\& method \-\- (both) parameters for \*(Aq\->envelope(method =>\*(Aq call
\& fault \-\- (both) parameters for \*(Aq\->envelope(fault =>\*(Aq call
\& freeform \-\- (both) parameters for \*(Aq\->envelope(freeform =>\*(Aq call
\& trace \-\- (both) trace enters into some important functions
\& debug \-\- (both) details about transport
.Ve
.PP
For example:
.PP
.Vb 2
\& use SOAP::Lite +trace =>
\& [qw(method fault)];
.Ve
.PP
lets you output the parameter values for all your fault/normal envelopes onto \s-1STDERR\s0.
If you want to log it you can either redirect \s-1STDERR\s0 to some file
.PP
.Vb 1
\& BEGIN { open(STDERR, \*(Aq>>....\*(Aq); }
.Ve
.PP
or (preferably) define your own function for a particular event:
.PP
.Vb 2
\& use SOAP::Lite +trace =>
\& [ method => sub {\*(Aqlog messages here\*(Aq}, fault => \e&log_faults ];
.Ve
.PP
You can share the same function for several events:
.PP
.Vb 2
\& use SOAP::Lite +trace =>
\& [method, fault => \e&log_methods_and_faults];
.Ve
.PP
Also you can use 'all' to get all available tracing and use '\-' in front of an event to disable particular event:
.PP
.Vb 2
\& use SOAP::Lite +trace =>
\& [ all, \-transport ]; # to get all logging without transport messages
.Ve
.PP
Finally,
.PP
.Vb 1
\& use SOAP::Lite +trace;
.Ve
.PP
will switch all debugging on.
.PP
You can use 'debug' instead of 'trace'. I prefer 'trace', others 'debug'.
Also \f(CW\*(C`on_debug\*(C'\fR is available for backward compatibility, as in
.PP
.Vb 1
\& use SOAP::Lite;
\&
\& my $s = SOAP::Lite
\& \-> uri(\*(Aqhttp://tempuri.org/\*(Aq)
\& \-> proxy(\*(Aqhttp://beta.search.microsoft.com/search/MSComSearchService.asmx\*(Aq)
\& \-> on_debug(sub{print@_}) # show you request/response with headers
\& ;
\& print $s\->GetVocabulary(SOAP::Data\->name(Query => \*(Aqsomething\*(Aq)\->uri(\*(Aqhttp://tempuri.org/\*(Aq))
\& \->valueof(\*(Aq//FOUND\*(Aq);
.Ve
.PP
or switch it on individually, with
.PP
.Vb 1
\& use SOAP::Lite +trace => debug;
.Ve
.PP
or
.PP
.Vb 1
\& use SOAP::Lite +trace => [debug => sub {\*(Aqdo_what_I_want_here\*(Aq}];
.Ve
.PP
Compare this with:
.PP
.Vb 1
\& use SOAP::Lite +trace => transport;
.Ve
.PP
which gives you access to \fBactual\fR request/response objects, so you can even
set/read cookies or do whatever you want there.
.PP
The difference between \f(CW\*(C`debug\*(C'\fR and \f(CW\*(C`transport\*(C'\fR is that \f(CW\*(C`transport\*(C'\fR will get
a HTTP::Request/HTTP::Response object and \f(CW\*(C`debug\*(C'\fR will get a stringified request
(\s-1NOT\s0 \s-1OBJECT\s0!). It can also be called in other places too.
.SS "SOAP::Transport"
.IX Subsection "SOAP::Transport"
Supports the \s-1SOAP\s0 Transport architecture. All transports must extend this
class.
.SS "SOAP::Fault"
.IX Subsection "SOAP::Fault"
This class gives you access to Fault generated on server side. To make a
Fault message you might simply die on server side and \s-1SOAP\s0 processor will
wrap you message as faultstring element and will transfer Fault on client
side. But in some cases you need to have more control over this process and
SOAP::Fault class gives it to you. To use it, simply die with SOAP::Fault
object as a parameter:
.PP
.Vb 4
\& die SOAP::Fault\->faultcode(\*(AqServer.Custom\*(Aq) # will be qualified
\& \->faultstring(\*(AqDied in server method\*(Aq)
\& \->faultdetail(bless {code => 1} => \*(AqBadError\*(Aq)
\& \->faultactor(\*(Aqhttp://www.soaplite.com/custom\*(Aq);
.Ve
.PP
\&\fIfaultdetail()\fR and \fIfaultactor()\fR methods are optional and since faultcode and
faultstring are required to represent fault message SOAP::Lite will use
default values ('Server' and 'Application error') if not specified.
.SS "SOAP::Utils"
.IX Subsection "SOAP::Utils"
This class gives you access to a number of subroutines to assist in data
formating, encoding, etc. Many of the subroutines are private, and are not
documented here, but a few are made public. They are:
.IP "format_datetime" 4
.IX Item "format_datetime"
.Vb 2
\& Returns a valid xsd:datetime string given a time object returned by
\& Perl\*(Aqs localtime function. Usage:
\&
\& print SOAP::Utils::format_datetime(localtime);
.Ve
.SS "SOAP::Constants"
.IX Subsection "SOAP::Constants"
This class gives you access to number of options that may affect behavior of
SOAP::Lite objects. They are not true contstants, aren't they?
.ie n .IP "$PATCH_HTTP_KEEPALIVE" 4
.el .IP "\f(CW$PATCH_HTTP_KEEPALIVE\fR" 4
.IX Item "$PATCH_HTTP_KEEPALIVE"
SOAP::Lite's \s-1HTTP\s0 Transport module attempts to provide a simple patch to
LWP::Protocol to enable \s-1HTTP\s0 Keep Alive. By default, this patch is turned
off, if however you would like to turn on the experimental patch change the
constant like so:
.Sp
.Vb 1
\& $SOAP::Constants::PATCH_HTTP_KEEPALIVE = 1;
.Ve
.ie n .IP "$DO_NOT_USE_XML_PARSER" 4
.el .IP "\f(CW$DO_NOT_USE_XML_PARSER\fR" 4
.IX Item "$DO_NOT_USE_XML_PARSER"
By default SOAP::Lite tries to load XML::Parser and if it fails, then to
load XML::Parser::Lite. You may skip the first step and use XML::Parser::Lite
even if XML::Parser is presented in your system if assign true value like this:
.Sp
.Vb 1
\& $SOAP::Constants::DO_NOT_USE_XML_PARSER = 1;
.Ve
.ie n .IP "$DO_NOT_USE_CHARSET" 4
.el .IP "\f(CW$DO_NOT_USE_CHARSET\fR" 4
.IX Item "$DO_NOT_USE_CHARSET"
By default SOAP::Lite specifies charset in content-type. Since not every
toolkit likes it you have an option to switch it off if you set
\&\f(CW$DO_NOT_USE_CHARSET\fR to true.
.ie n .IP "$DO_NOT_CHECK_CONTENT_TYPE" 4
.el .IP "\f(CW$DO_NOT_CHECK_CONTENT_TYPE\fR" 4
.IX Item "$DO_NOT_CHECK_CONTENT_TYPE"
By default SOAP::Lite verifies that content-type in successful response has
value 'multipart/related' or 'multipart/form\-data' for MIME-encoded messages
and 'text/xml' for all other ocassions. SOAP::Lite will raise exception for
all other values. \f(CW$DO_NOT_CHECK_CONTENT_TYPE\fR when set to true will allow
you to accept those values as valid.
.SH "FEATURES AND OPTIONS"
.IX Header "FEATURES AND OPTIONS"
.SS "\s-1DEFAULT\s0 \s-1SETTINGS\s0"
.IX Subsection "DEFAULT SETTINGS"
Though this feature looks similar to autodispatch they have (almost)
nothing in common. It lets you create default object and all objects
created after that will be cloned from default object and hence get its
properties. If you want to provide common \fIproxy()\fR or \fIuri()\fR settings for
all SOAP::Lite objects in your application you may do:
.PP
.Vb 4
\& use SOAP::Lite
\& proxy => \*(Aqhttp://localhost/cgi\-bin/soap.cgi\*(Aq,
\& uri => \*(Aqhttp://my.own.com/My/Examples\*(Aq
\& ;
\&
\& my $soap1 = new SOAP::Lite; # will get the same proxy()/uri() as above
\& print $soap1\->getStateName(1)\->result;
\&
\& my $soap2 = SOAP::Lite\->new; # same thing as above
\& print $soap2\->getStateName(2)\->result;
\&
\& # or you may override any settings you want
\& my $soap3 = SOAP::Lite\->proxy(\*(Aqhttp://localhost/\*(Aq);
\& print $soap3\->getStateName(1)\->result;
.Ve
.PP
\&\fBAny\fR SOAP::Lite properties can be propagated this way. Changes in object
copies will not affect global settings and you may still change global
settings with \f(CW\*(C`SOAP::Lite\->self\*(C'\fR call which returns reference to
global object. Provided parameter will update this object and you can
even set it to \f(CW\*(C`undef\*(C'\fR:
.PP
.Vb 1
\& SOAP::Lite\->self(undef);
.Ve
.PP
The \f(CW\*(C`use SOAP::Lite\*(C'\fR syntax also lets you specify default event handlers
for your code. If you have different \s-1SOAP\s0 objects and want to share the
same \f(CW\*(C`on_action()\*(C'\fR (or \f(CW\*(C`on_fault()\*(C'\fR for that matter) handler. You can
specify \f(CW\*(C`on_action()\*(C'\fR during initialization for every object, but
you may also do:
.PP
.Vb 3
\& use SOAP::Lite
\& on_action => sub {sprintf \*(Aq%s#%s\*(Aq, @_}
\& ;
.Ve
.PP
and this handler will be the default handler for all your \s-1SOAP\s0 objects.
You can override it if you specify a handler for a particular object.
See \fIt/*.t\fR for example of \fIon_fault()\fR handler.
.PP
Be warned, that since \f(CW\*(C`use ...\*(C'\fR is executed at compile time \fBall\fR \f(CW\*(C`use\*(C'\fR
statements will be executed \fBbefore\fR script execution that can make
unexpected results. Consider code:
.PP
.Vb 1
\& use SOAP::Lite proxy => \*(Aqhttp://localhost/\*(Aq;
\&
\& print SOAP::Lite\->getStateName(1)\->result;
\&
\& use SOAP::Lite proxy => \*(Aqhttp://localhost/cgi\-bin/soap.cgi\*(Aq;
\&
\& print SOAP::Lite\->getStateName(1)\->result;
.Ve
.PP
\&\fB\s-1BOTH\s0\fR \s-1SOAP\s0 calls will go to \f(CW\*(Aqhttp://localhost/cgi\-bin/soap.cgi\*(Aq\fR. If
you want to execute \f(CW\*(C`use\*(C'\fR at run-time, put it in \f(CW\*(C`eval\*(C'\fR:
.PP
.Vb 1
\& eval "use SOAP::Lite proxy => \*(Aqhttp://localhost/cgi\-bin/soap.cgi\*(Aq; 1" or die;
.Ve
.PP
or use
.PP
.Vb 1
\& SOAP::Lite\->self\->proxy(\*(Aqhttp://localhost/cgi\-bin/soap.cgi\*(Aq);
.Ve
.SS "\s-1IN/OUT\s0, \s-1OUT\s0 \s-1PARAMETERS\s0 \s-1AND\s0 \s-1AUTOBINDING\s0"
.IX Subsection "IN/OUT, OUT PARAMETERS AND AUTOBINDING"
SOAP::Lite gives you access to all parameters (both in/out and out) and
also does some additional work for you. Lets consider following example:
.PP
.Vb 5
\& <mehodResponse>
\& <res1>name1</res1>
\& <res2>name2</res2>
\& <res3>name3</res3>
\& </mehodResponse>
.Ve
.PP
In that case:
.PP
.Vb 4
\& $result = $r\->result; # gives you \*(Aqname1\*(Aq
\& $paramout1 = $r\->paramsout; # gives you \*(Aqname2\*(Aq, because of scalar context
\& $paramout1 = ($r\->paramsout)[0]; # gives you \*(Aqname2\*(Aq also
\& $paramout2 = ($r\->paramsout)[1]; # gives you \*(Aqname3\*(Aq
.Ve
.PP
or
.PP
.Vb 3
\& @paramsout = $r\->paramsout; # gives you ARRAY of out parameters
\& $paramout1 = $paramsout[0]; # gives you \*(Aqres2\*(Aq, same as ($r\->paramsout)[0]
\& $paramout2 = $paramsout[1]; # gives you \*(Aqres3\*(Aq, same as ($r\->paramsout)[1]
.Ve
.PP
Generally, if server returns \f(CW\*(C`return (1,2,3)\*(C'\fR you will get \f(CW1\fR as the result
and \f(CW2\fR and \f(CW3\fR as out parameters.
.PP
If the server returns \f(CW\*(C`return [1,2,3]\*(C'\fR you will get an \s-1ARRAY\s0 from \f(CW\*(C`result()\*(C'\fR and
\&\f(CW\*(C`undef\*(C'\fR from \f(CW\*(C`paramsout()\*(C'\fR .
Results can be arbitrary complex: they can be an array of something, they can
be objects, they can be anything and still be returned by \f(CW\*(C`result()\*(C'\fR . If only
one parameter is returned, \f(CW\*(C`paramsout()\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR.
.PP
But there is more.
If you have in your output parameters a parameter with the same
signature (name+type) as in the input parameters this parameter will be mapped
into your input automatically. Example:
.PP
\&\fBserver\fR:
.PP
.Vb 6
\& sub mymethod {
\& shift; # object/class reference
\& my $param1 = shift;
\& my $param2 = SOAP::Data\->name(\*(Aqmyparam\*(Aq => shift() * 2);
\& return $param1, $param2;
\& }
.Ve
.PP
\&\fBclient\fR:
.PP
.Vb 3
\& $a = 10;
\& $b = SOAP::Data\->name(\*(Aqmyparam\*(Aq => 12);
\& $result = $soap\->mymethod($a, $b);
.Ve
.PP
After that, \f(CW\*(C`$result == 10 and $b\->value == 24\*(C'\fR! Magic? Sort of.
Autobinding gives it to you. That will work with objects also with
one difference: you do not need to worry about the name and the type of
object parameter. Consider the \f(CW\*(C`PingPong\*(C'\fR example (\fIexamples/My/PingPong.pm\fR and
\&\fIexamples/pingpong.pl\fR):
.PP
\&\fBserver\fR:
.PP
.Vb 1
\& package My::PingPong;
\&
\& sub new {
\& my $self = shift;
\& my $class = ref($self) || $self;
\& bless {_num=>shift} => $class;
\& }
\&
\& sub next {
\& my $self = shift;
\& $self\->{_num}++;
\& }
.Ve
.PP
\&\fBclient\fR:
.PP
.Vb 4
\& use SOAP::Lite +autodispatch =>
\& uri => \*(Aqurn:\*(Aq,
\& proxy => \*(Aqhttp://localhost/\*(Aq
\& ;
\&
\& my $p = My::PingPong\->new(10); # $p\->{_num} is 10 now, real object returned
\& print $p\->next, "\en"; # $p\->{_num} is 11 now!, object autobinded
.Ve
.SS "\s-1AUTODISPATCHING\s0 \s-1AND\s0 \s-1SOAP::\s0 \s-1PREFIX\s0"
.IX Subsection "AUTODISPATCHING AND SOAP:: PREFIX"
\&\fB\s-1WARNING\s0\fR: \f(CW\*(C`autodispatch\*(C'\fR feature can have side effects for your application
and can affect functionality of other modules/libraries because of overloading
\&\s-1UNIVERSAL::AUTOLOAD\s0. All unresolved calls will be dispatched as \s-1SOAP\s0 calls,
however it could be not what you want in some cases. If so, consider using
object interface (see \f(CW\*(C`implementation of OO interface\*(C'\fR).
.PP
SOAP::Lite provides an autodispatching feature that lets you create
code which looks the same for local and remote access.
.PP
For example:
.PP
.Vb 4
\& use SOAP::Lite +autodispatch =>
\& uri => \*(Aqurn:/My/Examples\*(Aq,
\& proxy => \*(Aqhttp://localhost/\*(Aq
\& ;
.Ve
.PP
tells \s-1SOAP\s0 to 'autodispatch' all calls to the 'http://localhost/' endpoint with
the 'urn:/My/Examples' uri. All consequent method calls can look like:
.PP
.Vb 4
\& print getStateName(1), "\en";
\& print getStateNames(12,24,26,13), "\en";
\& print getStateList([11,12,13,42])\->[0], "\en";
\& print getStateStruct({item1 => 10, item2 => 4})\->{item2}, "\en";
.Ve
.PP
As you can see, there is no \s-1SOAP\s0 specific coding at all.
.PP
The same logic will work for objects as well:
.PP
.Vb 4
\& print "Session iterator\en";
\& my $p = My::SessionIterator\->new(10);
\& print $p\->next, "\en";
\& print $p\->next, "\en";
.Ve
.PP
This will access the remote My::SessionIterator module, gets an object, and then
calls remote methods again. The object will be transferred to the server, the
method is executed there and the result (and the modified object!) will be
transferred back to the client.
.PP
Autodispatch will work \fBonly\fR if you do not have the same method in your
code. For example, if you have \f(CW\*(C`use My::SessionIterator\*(C'\fR somewhere in your
code of our previous example, all methods will be resolved locally and no
\&\s-1SOAP\s0 calls will be done. If you want to get access to remote objects/methods
even in that case, use \f(CW\*(C`SOAP::\*(C'\fR prefix to your methods, like:
.PP
.Vb 1
\& print $p\->SOAP::next, "\en";
.Ve
.PP
See \f(CW\*(C`pingpong.pl\*(C'\fR for example of a script, that works with the same object
locally and remotely.
.PP
\&\f(CW\*(C`SOAP::\*(C'\fR prefix also gives you ability to access methods that have the same
name as methods of SOAP::Lite itself. For example, you want to call method
\&\fInew()\fR for your class \f(CW\*(C`My::PingPong\*(C'\fR through \s-1OO\s0 interface.
First attempt could be:
.PP
.Vb 5
\& my $s = SOAP::Lite
\& \-> uri(\*(Aqhttp://www.soaplite.com/My/PingPong\*(Aq)
\& \-> proxy(\*(Aqhttp://localhost/cgi\-bin/soap.cgi\*(Aq)
\& ;
\& my $obj = $s\->new(10);
.Ve
.PP
but it won't work, because SOAP::Lite has method \fInew()\fR itself. To provide
a hint, you should use \f(CW\*(C`SOAP::\*(C'\fR prefix and call will be dispatched remotely:
.PP
.Vb 1
\& my $obj = $s\->SOAP::new(10);
.Ve
.PP
You can mix autodispatch and usual \s-1SOAP\s0 calls in the same code if
you need it. Keep in mind, that calls with \s-1SOAP::\s0 prefix should always be a
method call, so if you want to call functions, use \f(CW\*(C`SOAP\->myfunction()\*(C'\fR
instead of \f(CW\*(C`SOAP::myfunction()\*(C'\fR.
.PP
Be warned though Perl has very flexible syntax some versions will complain
.PP
.Vb 1
\& Bareword "autodispatch" not allowed while "strict subs" in use ...
.Ve
.PP
if you try to put 'autodispatch' and '=>' on separate lines. So, keep them
on the same line, or put 'autodispatch' in quotes:
.PP
.Vb 3
\& use SOAP::Lite \*(Aqautodispatch\*(Aq # DON\*(AqT use plus in this case
\& => ....
\& ;
.Ve
.SS "\s-1ACCESSING\s0 \s-1HEADERS\s0 \s-1AND\s0 \s-1ENVELOPE\s0 \s-1ON\s0 \s-1SERVER\s0 \s-1SIDE\s0"
.IX Subsection "ACCESSING HEADERS AND ENVELOPE ON SERVER SIDE"
SOAP::Lite gives you direct access to all headers and the whole envelope on
the server side. Consider the following code from My::Parameters.pm:
.PP
.Vb 4
\& sub byname {
\& my($a, $b, $c) = @{pop\->method}{qw(a b c)};
\& return "a=$a, b=$b, c=$c";
\& }
.Ve
.PP
You will get this functionality \s-1ONLY\s0 if you inherit your class from
the SOAP::Server::Parameters class. This should keep existing code working and
provides this feature only when you need it.
.PP
Every method on server side will be called as class/object method, so it will
get an \fBobject reference\fR or a \fBclass name\fR as the first parameter, then the
method parameters, and then an envelope as \s-1SOAP::SOM\s0 object. Shortly:
.PP
.Vb 1
\& $self [, @parameters] , $envelope
.Ve
.PP
If you have a fixed number of parameters, you can do:
.PP
.Vb 2
\& my $self = shift;
\& my($param1, $param2) = @_;
.Ve
.PP
and ignore the envelope. If you need access to the envelope you can do:
.PP
.Vb 1
\& my $envelope = pop;
.Ve
.PP
since the envelope is always the last element in the parameters list.
The \f(CW\*(C`byname()\*(C'\fR method \f(CW\*(C`pop\->method\*(C'\fR will return a hash with
parameter names as hash keys and parameter values as hash values:
.PP
.Vb 1
\& my($a, $b, $c) = @{pop\->method}{qw(a b c)};
.Ve
.PP
gives you by-name access to your parameters.
.SS "\s-1SERVICE\s0 \s-1DEPLOYMENT\s0. \s-1STATIC\s0 \s-1AND\s0 \s-1DYNAMIC\s0"
.IX Subsection "SERVICE DEPLOYMENT. STATIC AND DYNAMIC"
Let us scrutinize the deployment process. When designing your \s-1SOAP\s0 server you
can consider two kind of deployment: \fBstatic\fR and \fBdynamic\fR.
For both, static and dynamic, you should specify \f(CW\*(C`MODULE\*(C'\fR,
\&\f(CW\*(C`MODULE::method\*(C'\fR, \f(CW\*(C`method\*(C'\fR or \f(CW\*(C`PATH/\*(C'\fR when creating \f(CW\*(C`use\*(C'\fRing the
SOAP::Lite module. The difference between static and dynamic deployment is
that in case of 'dynamic', any module which is not present will be loaded on
demand. See the \*(L"\s-1SECURITY\s0\*(R" section for detailed description.
.PP
Example for \fBstatic\fR deployment:
.PP
.Vb 2
\& use SOAP::Transport::HTTP;
\& use My::Examples; # module is preloaded
\&
\& SOAP::Transport::HTTP::CGI
\& # deployed module should be present here or client will get \*(Aqaccess denied\*(Aq
\& \-> dispatch_to(\*(AqMy::Examples\*(Aq)
\& \-> handle;
.Ve
.PP
Example for \fBdynamic\fR deployment:
.PP
.Vb 2
\& use SOAP::Transport::HTTP;
\& # name is unknown, module will be loaded on demand
\&
\& SOAP::Transport::HTTP::CGI
\& # deployed module should be present here or client will get \*(Aqaccess denied\*(Aq
\& \-> dispatch_to(\*(Aq/Your/Path/To/Deployed/Modules\*(Aq, \*(AqMy::Examples\*(Aq)
\& \-> handle;
.Ve
.PP
For static deployment you should specify the \s-1MODULE\s0 name directly.
For dynamic deployment you can specify the name either directly (in that
case it will be \f(CW\*(C`require\*(C'\fRd without any restriction) or indirectly, with a \s-1PATH\s0
In that case, the \s-1ONLY\s0 path that will be available will be the \s-1PATH\s0 given
to the \fIdispatch_to()\fR method). For information how to handle this situation
see \*(L"\s-1SECURITY\s0\*(R" section.
.PP
You should also use static binding when you have several different classes
in one file and want to make them available for \s-1SOAP\s0 calls.
.PP
\&\fB\s-1SUMMARY\s0\fR:
.PP
.Vb 6
\& dispatch_to(
\& # dynamic dispatch that allows access to ALL modules in specified directory
\& PATH/TO/MODULES
\& # 1. specifies directory
\& # \-\- AND \-\-
\& # 2. gives access to ALL modules in this directory without limits
\&
\& # static dispatch that allows access to ALL methods in particular MODULE
\& MODULE
\& # 1. gives access to particular module (all available methods)
\& # PREREQUISITES:
\& # module should be loaded manually (for example with \*(Aquse ...\*(Aq)
\& # \-\- OR \-\-
\& # you can still specify it in PATH/TO/MODULES
\&
\& # static dispatch that allows access to particular method ONLY
\& MODULE::method
\& # same as MODULE, but gives access to ONLY particular method,
\& # so there is not much sense to use both MODULE and MODULE::method
\& # for the same MODULE
\& )
.Ve
.PP
In addition to this SOAP::Lite also supports experimental syntax that
allows you bind specific \s-1URL\s0 or SOAPAction to \s-1CLASS/MODULE\s0 or object:
.PP
.Vb 5
\& dispatch_with({
\& URI => MODULE, # \*(Aqhttp://www.soaplite.com/\*(Aq => \*(AqMy::Class\*(Aq,
\& SOAPAction => MODULE, # \*(Aqhttp://www.soaplite.com/method\*(Aq => \*(AqAnother::Class\*(Aq,
\& URI => object, # \*(Aqhttp://www.soaplite.com/obj\*(Aq => My::Class\->new,
\& })
.Ve
.PP
\&\s-1URI\s0 is checked before SOAPAction. You may use both \f(CW\*(C`dispatch_to()\*(C'\fR and
\&\f(CW\*(C`dispatch_with()\*(C'\fR syntax and \f(CW\*(C`dispatch_with()\*(C'\fR has more priority, so
first checked \s-1URI\s0, then SOAPAction and only then will be checked
\&\f(CW\*(C`dispatch_to()\*(C'\fR. See \fIt/03\-server.t\fR for more information and examples.
.SS "\s-1SECURITY\s0"
.IX Subsection "SECURITY"
Due to security reasons, the current path for perl modules (\f(CW@INC\fR) will be disabled
once you have chosen dynamic deployment and specified your own \f(CW\*(C`PATH/\*(C'\fR.
If you want to access other modules in your included package you have
several options:
.IP "1." 4
Switch to static linking:
.Sp
.Vb 2
\& use MODULE;
\& $server\->dispatch_to(\*(AqMODULE\*(Aq);
.Ve
.Sp
It can be useful also when you want to import something specific
from the deployed modules:
.Sp
.Vb 1
\& use MODULE qw(import_list);
.Ve
.IP "2." 4
Change \f(CW\*(C`use\*(C'\fR to \f(CW\*(C`require\*(C'\fR. The path is unavailable only during
the initialization part, and it is available again during execution.
So, if you do \f(CW\*(C`require\*(C'\fR somewhere in your package, it will work.
.IP "3." 4
Same thing, but you can do:
.Sp
.Vb 1
\& eval \*(Aquse MODULE qw(import_list)\*(Aq; die if $@;
.Ve
.IP "4." 4
Assign a \f(CW@INC\fR directory in your package and then make \f(CW\*(C`use\*(C'\fR.
Don't forget to put \f(CW@INC\fR in \f(CW\*(C`BEGIN{}\*(C'\fR block or it won't work:
.Sp
.Vb 1
\& BEGIN { @INC = qw(my_directory); use MODULE }
.Ve
.SS "\s-1COMPRESSION\s0"
.IX Subsection "COMPRESSION"
SOAP::Lite provides you option for enabling compression on wire (for \s-1HTTP\s0
transport only). Both server and client should support this capability,
but this logic should be absolutely transparent for your application.
.PP
Compression can be enabled by specifying threshold for compression on client
or server side:
.IP "Client" 4
.IX Item "Client"
.Vb 6
\& print SOAP::Lite
\& \-> uri(\*(Aqhttp://localhost/My/Parameters\*(Aq)
\& \-> proxy(\*(Aqhttp://localhost/\*(Aq, options => {compress_threshold => 10000})
\& \-> echo(1 x 10000)
\& \-> result
\& ;
.Ve
.IP "Server" 4
.IX Item "Server"
.Vb 4
\& my $server = SOAP::Transport::HTTP::CGI
\& \-> dispatch_to(\*(AqMy::Parameters\*(Aq)
\& \-> options({compress_threshold => 10000})
\& \-> handle;
.Ve
.PP
For more information see \s-1COMPRESSION\s0 section
in \s-1HTTP\s0 transport documentation.
.SS "OBJECTS-BY-REFERENCE"
.IX Subsection "OBJECTS-BY-REFERENCE"
SOAP::Lite implements an experimental (yet functional) support for
objects-by-reference. You should not see any difference on the client side
when using this. On the server side you should specify the names of the
classes you want to be returned by reference (instead of by value) in the
\&\f(CW\*(C`objects_by_reference()\*(C'\fR method for your server implementation (see
soap.pop3, soap.daemon and Apache.pm).
.PP
Garbage collection is done on the server side (not earlier than after 600
seconds of inactivity time), and you can overload the default behavior with
specific functions for any particular class.
.PP
Binding does not have any special syntax and is implemented on server side
(see the differences between My::SessionIterator and My::PersistentIterator).
On the client side, objects will have same type/class as before
(\f(CW\*(C`My::SessionIterator\->new()\*(C'\fR will return an object of class
My::SessionIterator). However, this object is just a stub with an object \s-1ID\s0
inside.
.SS "\s-1INTEROPERABILITY\s0"
.IX Subsection "INTEROPERABILITY"
.IP "Microsoft's .NET" 4
.IX Item "Microsoft's .NET"
To use .NET client and SOAP::Lite server
.RS 4
.IP "qualify all elements" 4
.IX Item "qualify all elements"
use fully qualified names for your return values, e.g.:
.Sp
.Vb 4
\& return SOAP::Data\->name(\*(Aqmyname\*(Aq)
\& \->type(\*(Aqstring\*(Aq)
\& \->uri(\*(Aqhttp://tempuri.org/\*(Aq)
\& \->value($output);
.Ve
.Sp
Use namespace that you specify for \s-1URI\s0 instead of 'http://tempuri.org/'.
.Sp
In addition see comment about default incoding in .NET Web Services below.
.RE
.RS 4
.Sp
To use SOAP::Lite client and .NET server
.IP "declare proper soapAction (uri/method) in your call" 4
.IX Item "declare proper soapAction (uri/method) in your call"
For example, use \f(CW\*(C`on_action(sub{join \*(Aq\*(Aq, @_})\*(C'\fR.
.IP "disable charset in content-type" 4
.IX Item "disable charset in content-type"
Specify \f(CW\*(C`$SOAP::Constants::DO_NOT_USE_CHARSET = 1\*(C'\fR somewhere in your code
after \f(CW\*(C`use SOAP::Lite\*(C'\fR if you are getting error:
.Sp
.Vb 2
\& Server found request content type to be \*(Aqtext/xml; charset=utf\-8\*(Aq,
\& but expected \*(Aqtext/xml\*(Aq
.Ve
.IP "qualify all elements" 4
.IX Item "qualify all elements"
Any of following actions should work:
.RS 4
.IP "use fully qualified name for method parameters" 4
.IX Item "use fully qualified name for method parameters"
Use \f(CW\*(C`SOAP::Data\->name(Query => \*(Aqbiztalk\*(Aq)\->uri(\*(Aqhttp://tempuri.org/\*(Aq)\*(C'\fR instead of
\&\f(CW\*(C`SOAP::Data\->name(\*(AqQuery\*(Aq => \*(Aqbiztalk\*(Aq)\*(C'\fR.
.Sp
Example of SOAPsh call (all parameters should be in one line):
.Sp
.Vb 5
\& > perl SOAPsh.pl
\& "http://beta.search.microsoft.com/search/mscomsearchservice.asmx"
\& "http://tempuri.org/"
\& "on_action(sub{join \*(Aq\*(Aq, @_})"
\& "GetVocabulary(SOAP::Data\->name(Query => \*(Aqbiztalk\*(Aq)\->uri(\*(Aqhttp://tempuri.org/\*(Aq))"
.Ve
.IP "make method in default namespace" 4
.IX Item "make method in default namespace"
instead of
.Sp
.Vb 3
\& my @rc = $soap\->call(add => @parms)\->result;
\& # \-\- OR \-\-
\& my @rc = $soap\->add(@parms)\->result;
.Ve
.Sp
use
.Sp
.Vb 3
\& my $method = SOAP::Data\->name(\*(Aqadd\*(Aq)
\& \->attr({xmlns => \*(Aqhttp://tempuri.org/\*(Aq});
\& my @rc = $soap\->call($method => @parms)\->result;
.Ve
.IP "modify .NET server if you are in charge for that" 4
.IX Item "modify .NET server if you are in charge for that"
Stefan Pharies <stefanph@microsoft.com>:
.Sp
SOAP::Lite uses the \s-1SOAP\s0 encoding (section 5 of the soap 1.1 spec), and
the default for .NET Web Services is to use a literal encoding. So
elements in the request are unqualified, but your service expects them to
be qualified. .Net Web Services has a way for you to change the expected
message format, which should allow you to get your interop working.
At the top of your class in the asmx, add this attribute (for Beta 1):
.Sp
.Vb 1
\& [SoapService(Style=SoapServiceStyle.RPC)]
.Ve
.Sp
Another source said it might be this attribute (for Beta 2):
.Sp
.Vb 1
\& [SoapRpcService]
.Ve
.Sp
Full Web Service text may look like:
.Sp
.Vb 4
\& <%@ WebService Language="C#" Class="Test" %>
\& using System;
\& using System.Web.Services;
\& using System.Xml.Serialization;
\&
\& [SoapService(Style=SoapServiceStyle.RPC)]
\& public class Test : WebService {
\& [WebMethod]
\& public int add(int a, int b) {
\& return a + b;
\& }
\& }
.Ve
.Sp
Another example from Kirill Gavrylyuk <kirillg@microsoft.com>:
.Sp
\&\*(L"You can insert [\fISoapRpcService()\fR] attribute either on your class or on
operation level\*(R".
.Sp
.Vb 1
\& <%@ WebService Language=CS class="DataType.StringTest"%>
\&
\& namespace DataType {
\&
\& using System;
\& using System.Web.Services;
\& using System.Web.Services.Protocols;
\& using System.Web.Services.Description;
\&
\& [SoapRpcService()]
\& public class StringTest: WebService {
\& [WebMethod]
\& [SoapRpcMethod()]
\& public string RetString(string x) {
\& return(x);
\& }
\& }
\& }
.Ve
.Sp
Example from Yann Christensen <yannc@microsoft.com>:
.Sp
.Vb 3
\& using System;
\& using System.Web.Services;
\& using System.Web.Services.Protocols;
\&
\& namespace Currency {
\& [WebService(Namespace="http://www.yourdomain.com/example")]
\& [SoapRpcService]
\& public class Exchange {
\& [WebMethod]
\& public double getRate(String country, String country2) {
\& return 122.69;
\& }
\& }
\& }
.Ve
.RE
.RS 4
.RE
.RE
.RS 4
.Sp
Thanks to
Petr Janata <petr.janata@i.cz>,
Stefan Pharies <stefanph@microsoft.com>,
Brian Jepson <bjepson@jepstone.net>, and others
for description and examples.
.RE
.SS "\s-1TROUBLESHOOTING\s0"
.IX Subsection "TROUBLESHOOTING"
.IP "+autodispatch doesn't work in Perl 5.8" 4
.IX Item "+autodispatch doesn't work in Perl 5.8"
There is a bug in Perl 5.8's \s-1UNIVERSAL::AUTOLOAD\s0 functionality that prevents
the +autodispatch functionality from working properly. The workaround is to
use dispatch_from instead. Where you might normally do something like this:
.Sp
.Vb 4
\& use Some::Module;
\& use SOAP::Lite +autodispatch =>
\& uri => \*(Aqurn:Foo\*(Aq
\& proxy => \*(Aqhttp://...\*(Aq;
.Ve
.Sp
You would do something like this:
.Sp
.Vb 3
\& use SOAP::Lite dispatch_from(Some::Module) =>
\& uri => \*(Aqurn:Foo\*(Aq
\& proxy => \*(Aqhttp://...\*(Aq;
.Ve
.IP "\s-1HTTP\s0 transport" 4
.IX Item "HTTP transport"
See \s-1TROUBLESHOOTING\s0 section in
documentation for \s-1HTTP\s0 transport.
.IP "\s-1COM\s0 interface" 4
.IX Item "COM interface"
.RS 4
.PD 0
.ie n .IP "Can't call method ""server"" on undefined value" 4
.el .IP "Can't call method ``server'' on undefined value" 4
.IX Item "Can't call method server on undefined value"
.PD
Probably you didn't register Lite.dll with 'regsvr32 Lite.dll'
.IP "Failed to load PerlCtrl runtime" 4
.IX Item "Failed to load PerlCtrl runtime"
Probably you have two Perl installations in different places and
ActiveState's Perl isn't the first Perl specified in \s-1PATH\s0. Rename the
directory with another Perl (at least during the \s-1DLL\s0's startup) or put
ActiveState's Perl on the first place in \s-1PATH\s0.
.RE
.RS 4
.RE
.IP "\s-1XML\s0 Parsers" 4
.IX Item "XML Parsers"
.RS 4
.PD 0
.IP "\s-1SAX\s0 parsers" 4
.IX Item "SAX parsers"
.PD
\&\s-1SAX\s0 2.0 has a known bug in org.xml.sax.helpers.ParserAdapter
rejects Namespace prefix used before declaration
.Sp
(http://www.megginson.com/SAX/index.html).
.Sp
That means that in some cases \s-1SOAP\s0 messages created by SOAP::Lite may not
be parsed properly by SAX2/Java parser, because Envelope
element contains namespace declarations and attributes that depends on this
declarations. According to \s-1XML\s0 specification order of these attributes is
not significant. SOAP::Lite does \s-1NOT\s0 have a problem parsing such messages.
.Sp
Thanks to Steve Alpert (Steve_Alpert@idx.com) for pointing on it.
.RE
.RS 4
.RE
.SS "\s-1PERFORMANCE\s0"
.IX Subsection "PERFORMANCE"
.IP "Processing of \s-1XML\s0 encoded fragments" 4
.IX Item "Processing of XML encoded fragments"
SOAP::Lite is based on XML::Parser which is basically wrapper around James
Clark's expat parser. Expat's behavior for parsing \s-1XML\s0 encoded string can
affect processing messages that have lot of encoded entities, like \s-1XML\s0
fragments, encoded as strings. Providing low-level details, parser will call
\&\fIchar()\fR callback for every portion of processed stream, but individually for
every processed entity or newline. It can lead to lot of calls and additional
memory manager expenses even for small messages. By contrast, \s-1XML\s0 messages
which are encoded as base64, don't have this problem and difference in
processing time can be significant. For \s-1XML\s0 encoded string that has about 20
lines and 30 tags, number of call could be about 100 instead of one for
the same string encoded as base64.
.Sp
Since it is parser's feature there is \s-1NO\s0 fix for this behavior (let me know
if you find one), especially because you need to parse message you already
got (and you cannot control content of this message), however, if your are
in charge for both ends of processing you can switch encoding to base64 on
sender's side. It will definitely work with SOAP::Lite and it \fBmay\fR work with
other toolkits/implementations also, but obviously I cannot guarantee that.
.Sp
If you want to encode specific string as base64, just do
\&\f(CW\*(C`SOAP::Data\->type(base64 => $string)\*(C'\fR either on client or on server
side. If you want change behavior for specific instance of SOAP::Lite, you
may subclass \f(CW\*(C`SOAP::Serializer\*(C'\fR, override \f(CW\*(C`as_string()\*(C'\fR method that is
responsible for string encoding (take a look into \f(CW\*(C`as_base64()\*(C'\fR) and
specify \fBnew\fR serializer class for your SOAP::Lite object with:
.Sp
.Vb 3
\& my $soap = new SOAP::Lite
\& serializer => My::Serializer\->new,
\& ..... other parameters
.Ve
.Sp
or on server side:
.Sp
.Vb 3
\& my $server = new SOAP::Transport::HTTP::Daemon # or any other server
\& serializer => My::Serializer\->new,
\& ..... other parameters
.Ve
.Sp
If you want to change this behavior for \fBall\fR instances of SOAP::Lite, just
substitute \f(CW\*(C`as_string()\*(C'\fR method with \f(CW\*(C`as_base64()\*(C'\fR somewhere in your
code \fBafter\fR \f(CW\*(C`use SOAP::Lite\*(C'\fR and \fBbefore\fR actual processing/sending:
.Sp
.Vb 1
\& *SOAP::Serializer::as_string = \e&SOAP::Serializer::as_base64;
.Ve
.Sp
Be warned that last two methods will affect \fBall\fR strings and convert them
into base64 encoded. It doesn't make any difference for SOAP::Lite, but it
\&\fBmay\fR make a difference for other toolkits.
.SS "\s-1WEBHOSTING\s0 \s-1INSTALLATION\s0"
.IX Subsection "WEBHOSTING INSTALLATION"
As soon as you have telnet access to the box and XML::Parser is already
installed there (or you have Perl 5.6 and can use XML::Parser::Lite) you
may install your own copy of SOAP::Lite even if hosting provider doesn't
want to do it.
.PP
Setup \f(CW\*(C`PERL5LIB\*(C'\fR environment variable. Depending on your shell it may
look like:
.PP
.Vb 1
\& PERL5LIB=/you/home/directory/lib; export PERL5LIB
.Ve
.PP
\&\f(CW\*(C`lib\*(C'\fR here is the name of directory where all libraries will be installed
under your home directory.
.PP
Run \s-1CPAN\s0 module with
.PP
.Vb 1
\& perl \-MCPAN \-e shell
.Ve
.PP
and run three commands from \s-1CPAN\s0 shell
.PP
.Vb 3
\& > o conf make_arg \-I~/lib
\& > o conf make_install_arg \-I~/lib
\& > o conf makepl_arg LIB=~/lib PREFIX=~ INSTALLMAN1DIR=~/man/man1 INSTALLMAN3DIR=~/man/man3
.Ve
.PP
\&\f(CW\*(C`LIB\*(C'\fR will specify directory where all libraries will reside.
.PP
\&\f(CW\*(C`PREFIX\*(C'\fR will specify prefix for all directories (like \fIlib\fR, \fIbin\fR, \fIman\fR,
though it doesn't work in all cases for some reason).
.PP
\&\f(CW\*(C`INSTALLMAN1DIR\*(C'\fR and \f(CW\*(C`INSTALLMAN3DIR\*(C'\fR specify directories for manuals
(if you don't specify them, install will fail because it'll try to setup
it in default directory and you don't have permissions for that).
.PP
Then run:
.PP
.Vb 1
\& > install SOAP::Lite
.Ve
.PP
Now in your scripts you need to specify:
.PP
.Vb 1
\& use lib \*(Aq/your/home/directory/lib\*(Aq;
.Ve
.PP
somewhere before \f(CW\*(Aquse SOAP::Lite;\*(Aq\fR
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
.IP "\(bu" 4
No support for multidimensional, partially transmitted and sparse arrays
(however arrays of arrays are supported, as well as any other data
structures, and you can add your own implementation with SOAP::Data).
.IP "\(bu" 4
Limited support for \s-1WSDL\s0 schema.
.IP "\(bu" 4
XML::Parser::Lite relies on Unicode support in Perl and doesn't do
entity decoding.
.IP "\(bu" 4
Limited support for mustUnderstand and Actor attributes.
.SH "PLATFORMS"
.IX Header "PLATFORMS"
.IP "MacOS" 4
.IX Item "MacOS"
Information about XML::Parser for MacPerl could be found here:
http://bumppo.net/lists/macperl\-modules/1999/07/msg00047.html
.Sp
Compiled XML::Parser for MacOS could be found here:
http://www.perl.com/CPAN\-local/authors/id/A/AS/ASANDSTRM/XML\-Parser\-2.27\-bin\-1\-MacOS.tgz
.SH "AVAILABILITY"
.IX Header "AVAILABILITY"
You can download the latest version SOAP::Lite for Unix or SOAP::Lite for Win32 from the following sources:
.PP
* SOAP::Lite Homepage: http://soaplite.com/
* \s-1CPAN:\s0 http://search.cpan.org/search?dist=SOAP\-Lite
* Sourceforge: http://sourceforge.net/projects/soaplite/
.PP
You are welcome to send e\-mail to the maintainers of SOAP::Lite with your
with your comments, suggestions, bug reports and complaints.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1SOAP\s0 SOAP/Perl library from Keith Brown ( http://www.develop.com/soap/ ) or
( http://search.cpan.org/search?dist=SOAP )
.SH "ACKNOWLEDGMENTS"
.IX Header "ACKNOWLEDGMENTS"
A lot of thanks to
Tony Hong <thong@xmethods.net>,
Petr Janata <petr.janata@i.cz>,
Murray Nesbitt <murray@ActiveState.com>,
Robert Barta <rho@bigpond.net.au>,
Gisle Aas <gisle@ActiveState.com>,
Carl K. Cunningham <cc@roberts.de>,
Graham Glass <graham\-glass@mindspring.com>,
Chris Radcliff <chris@velocigen.com>,
Arun Kumar <u_arunkumar@yahoo.com>,
and many many others
.PP
for providing help, feedback, support, patches and comments.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2000\-2004 Paul Kulchenko. All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "AUTHORS"
.IX Header "AUTHORS"
Paul Kulchenko (paulclinger@yahoo.com)
Byrne Reese (byrne@majordojo.com)
Cokiee Shell Web 1.0, Coded By Razor
Neueste Kommentare