Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XML::Compile::WSDL11(3User Contributed Perl DocumentatiXML::Compile::WSDL11(3)

NAME
       XML::Compile::WSDL11 - create SOAP messages defined by WSDL 1.1

INHERITANCE
	XML::Compile::WSDL11
	  is a XML::Compile::Cache
	  is a XML::Compile::Schema
	  is a XML::Compile

SYNOPSIS
	# preparation
	use XML::Compile::WSDL11;      # use WSDL version 1.1
	use XML::Compile::SOAP11;      # use SOAP version 1.1
	use XML::Compile::Transport::SOAPHTTP;

	# you want some	trace?
	use Log::Report	mode =>	'DEBUG';   # or	'VERBOSE'

	# collect one or more wsdls and	xsds in	one object
	my $wsdl = XML::Compile::WSDL11->new($wsdlfile
	  , server_type	=> 'BEA'
	  );
	$wsdl->addWSDL(...more WSDL files...);
	$wsdl->importDefinitions(...more schemas...);

	# during initiation, for each used call
	my $call = $wsdl->compileClient('GetStockPrice', ...);

	# at "run-time", call as often as you want (fast)
	my $answer = $call->(%request);

	# capture useful trace information
	my ($answer, $trace) = $call->(%request);
	if($trace->errors)
	{   $trace->printError;
	}

	# no need to administer	the operations by hand:	alternative
	$wsdl->compileCalls;  #	at initiation
	my $answer = $wsdl->call(GetStockPrice => %request);

	# investigate the %request structure (server input)
	print $wsdl->explain('GetStockPrice', PERL => 'INPUT', recurse => 1);

	# investigate the $answer structure (server output)
	print $wsdl->explain('GetStockPrice', PERL => 'OUTPUT');

	# when you like, get all operation definitions
	my @all_ops = $wsdl->operations;

	# Install XML::Compile::SOAP::Daemon
	my $server  = XML::Compile::SOAP::HTTPDaemon->new;
	$server->operationsFromWSDL($wsdl);
	undef $wsdl;	# not needed any further

	# For debug info, start	your script with:
	use Log::Report	mode =>	'DEBUG';

DESCRIPTION
       This module understands WSDL version 1.1.  An WSDL file defines a set
       of messages to be send and received over	(SOAP) connections. This
       involves	encoding of the	message	to be send into	XML, sending the
       message to the server, collect the answer, and finally decoding the XML
       to Perl.

       As end-user, you	do not have to worry about the complex details of the
       messages	and the	way to exchange	them: it's all simple Perl for you.
       Also, faults are	handled	automatically.	The only complication you have
       to worry	about is to shape a nested HASH	structure to the sending
       message structure.  XML::Compile::Schema::template() may	help you.

       When the	definitions are	spread over multiple files you will need to
       use addWSDL() (wsdl) or importDefinitions() (additional schema's)
       explicitly. Usually, interreferences between those files	are broken.
       Often they reference over networks (you should never trust). So,	on
       purpose you must	explicitly load	the files you need from	local disk!
       (of course, it is simple	to find	one-liners as work-arounds, but	I will
       not tell	you how!  See XML::Compile::SOAP::FAQ)

       Extends "DESCRIPTION" in	XML::Compile::Cache.

METHODS
       Extends "METHODS" in XML::Compile::Cache.

   Constructors
       Extends "Constructors" in XML::Compile::Cache.

       XML::Compile::WSDL11->new( [$xml], %options )
	   The $xml is the WSDL	file, which is anything	accepted by
	   XML::Compile::dataToXML().

	    -Option	       --Defined in	     --Default
	     allow_undeclared	 XML::Compile::Cache   <false>
	     any_element	 XML::Compile::Cache   'ATTEMPT'
	     block_namespace	 XML::Compile::Schema  []
	     hook		 XML::Compile::Schema  undef
	     hooks		 XML::Compile::Schema  []
	     ignore_unused_tags	 XML::Compile::Schema  <false>
	     key_rewrite	 XML::Compile::Schema  []
	     opts_readers	 XML::Compile::Cache   []
	     opts_rw		 XML::Compile::Cache   []
	     opts_writers	 XML::Compile::Cache   []
	     parser_options	 XML::Compile	       <many>
	     prefixes		 XML::Compile::Cache   <smart>
	     schema_dirs	 XML::Compile	       undef
	     server_type			       undef
	     typemap		 XML::Compile::Cache   {}
	     xsi_type		 XML::Compile::Cache   {}

	   allow_undeclared => BOOLEAN
	   any_element => CODE|'TAKE_ALL'|'SKIP_ALL'|'ATTEMPT'|'SLOPPY'
	   block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY
	   hook	=> HOOK|ARRAY
	   hooks => ARRAY
	   ignore_unused_tags => BOOLEAN|REGEXP
	   key_rewrite => HASH|CODE|ARRAY
	   opts_readers	=> HASH|ARRAY-of-PAIRS
	   opts_rw => HASH|ARRAY-of-PAIRS
	   opts_writers	=> HASH|ARRAY-of-PAIRS
	   parser_options => HASH|ARRAY
	   prefixes => HASH|ARRAY-of-PAIRS
	   schema_dirs => DIRECTORY|ARRAY-OF-DIRECTORIES
	   server_type => NAME
	     [3.01] When you specify the implementation	of the server, we can
	     work around some of the known bugs	and limitation.	 Read
	     XML::Compile::SOAP	section	"Supported servers" for	supported
	     servers.

	   typemap => HASH|ARRAY
	   xsi_type => HASH|ARRAY

   Accessors
       Extends "Accessors" in XML::Compile::Cache.

       $obj->addHook($hook|LIST|undef)
	   Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addHooks( $hook, [$hook, ...] )
	   Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addKeyRewrite($predef|CODE|HASH, ...)
	   Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addSchemaDirs(@directories|$filename)
       XML::Compile::WSDL11->addSchemaDirs(@directories|$filename)
	   Inherited, see "Accessors" in XML::Compile

       $obj->addSchemas($xml, %options)
	   Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addTypemap(PAIR)
	   Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addTypemaps(PAIRS)
	   Inherited, see "Accessors" in XML::Compile::Schema

       $obj->addXsiType( [HASH|ARRAY|LIST] )
	   Inherited, see "Accessors" in XML::Compile::Cache

       $obj->allowUndeclared( [BOOLEAN]	)
	   Inherited, see "Accessors" in XML::Compile::Cache

       $obj->anyElement('ATTEMPT'|'SLOPPY'|'SKIP_ALL'|'TAKE_ALL'|CODE)
	   Inherited, see "Accessors" in XML::Compile::Cache

       $obj->blockNamespace($ns|$type|HASH|CODE|ARRAY)
	   Inherited, see "Accessors" in XML::Compile::Schema

       $obj->hooks( [<'READER'|'WRITER'>] )
	   Inherited, see "Accessors" in XML::Compile::Schema

       $obj->typemap( [HASH|ARRAY|PAIRS] )
	   Inherited, see "Accessors" in XML::Compile::Cache

       $obj->useSchema(	$schema, [$schema, ...]	)
	   Inherited, see "Accessors" in XML::Compile::Schema

   Prefix management
       Extends "Prefix management" in XML::Compile::Cache.

       $obj->addNicePrefix(BASE, NAMESPACE)
	   Inherited, see "Prefix management" in XML::Compile::Cache

       $obj->addPrefixes( [PAIRS|ARRAY|HASH] )
	   Inherited, see "Prefix management" in XML::Compile::Cache

       $obj->learnPrefixes($node)
	   Inherited, see "Prefix management" in XML::Compile::Cache

       $obj->prefix($prefix)
	   Inherited, see "Prefix management" in XML::Compile::Cache

       $obj->prefixFor($uri)
	   Inherited, see "Prefix management" in XML::Compile::Cache

       $obj->prefixed( $type|<$ns,$local> )
	   Inherited, see "Prefix management" in XML::Compile::Cache

       $obj->prefixes( [$params] )
	   Inherited, see "Prefix management" in XML::Compile::Cache

   Compilers
       Extends "Compilers" in XML::Compile::Cache.

       $obj->addCompileOptions(	['READERS'|'WRITERS'|'RW'], %options )
	   Inherited, see "Compilers" in XML::Compile::Cache

       $obj->call($opname, $data)
	   [2.20] Call the $opname (operation name) with $data (HASH or	LIST
	   of parameters).  This only works when you have called
	   compileCalls() beforehand, always during the	initiation phase of
	   the program.

	   example:

	      #	at initiation time (compile once)
	      $wsdl->compileCalls;

	      #	at runtime (run	often)
	      my $answer = $wsdl->call($operation, $request);

       $obj->compile( <'READER'|'WRITER'>, $type, %options )
	   Inherited, see "Compilers" in XML::Compile::Schema

       $obj->compileAll( [ <'READERS'|'WRITERS'|'RW'|'CALLS'>, [$ns] ] )
	   [2.20] With explicit	"CALLS"	or without any parameter, it will call
	   compileCalls(). Otherwise, see XML::Compile::Cache::compileAll().

       $obj->compileCall($operation|$opname, %options)
	   [2.37] The call to the $operation object (which extends
	   XML::Compile::SOAP::Operation) gets compiled	and cached so it can
	   be used with	call().

	   [2.38] Alteratively to an $operation	object,	you may	also specify
	   an operation	by name.

	    -Option--Default
	     alias   undef

	   alias => NAME
	     [3.03] When defined, the compiled operation will be stored	with
	     the alias name in stead of	the operation name.  This may make
	     your code more readible or	solve naming conflicts.

	   example:

	     my	$op = $wsdl->operation(name => 'getInfo');
	     $wsdl->compileCall($op);

	     # as often	as you need it
	     my	($answer, $trace) = $wsdl->call('getInfo')->(%request);

       $obj->compileCalls(%options)
	   [2.20] Compile a handler for	each of	the available operations. The
	   %options are	passed to each call of compileClient(),	but will be
	   overruled by	more specific declared options.

	   Additionally, %options can contain "service", "port", and "binding"
	   to limit the	set of involved	calls. See operations()	for details on
	   these options.

	   You may declare additional specific compilation options with	the
	   declare() method.

	    -Option    --Default
	     long_names	 false

	   long_names => BOOLEAN
	     [3.03] Prepend the	service	name to	the operation name to produce
	     an	alias (see compileCall(alias)) for the compiled	call.  If the
	     service name is 'X' and the operation name	is 'Y',	then the alias
	     becomes 'X#Y'.

	     You will need this	if you have multiple operations	with the same
	     name in your WSDL (-collection).

	   example:

	      my $trans	= XML::Compile::Transport::SOAPHTTP
		->new(timeout => 500, address => $wsdl->endPoint);
	      $wsdl->compileCalls(transport => $trans);

	      #	alternatives for simple	cases
	      $wsdl->compileAll('CALLS');
	      $wsdl->compileAll;

	      my $answer = $wsdl->call($myop, $request);

       $obj->compileType( <'READER'|'WRITER'>, $type, %options )
	   Inherited, see "Compilers" in XML::Compile::Schema

       $obj->dataToXML($node|REF-XML|XML-STRING|$filename|$fh|$known)
       XML::Compile::WSDL11->dataToXML($node|REF-XML|XML-STRING|$filename|$fh|$known)
	   Inherited, see "Compilers" in XML::Compile

       $obj->initParser(%options)
       XML::Compile::WSDL11->initParser(%options)
	   Inherited, see "Compilers" in XML::Compile

       $obj->reader($type|$name, %options)
	   Inherited, see "Compilers" in XML::Compile::Cache

       $obj->template( <'XML'|'PERL'|'TREE'>, $element,	%options )
	   Inherited, see "Compilers" in XML::Compile::Schema

       $obj->writer($type|$name)
	   Inherited, see "Compilers" in XML::Compile::Cache

   Extension
       $obj->addWSDL($xmldata|\@xmldata, %options)
	   The $xmldata	must be	acceptable to XML::Compile::dataToXML()	and
	   should represent the	top-level of a (partial) WSDL document.	 The
	   specification can be	spread over multiple files, each of which must
	   have	a "definition" root element.

       $obj->compileClient( [$name], %options )
	   Creates an XML::Compile::SOAP::Operation temporary object using
	   operation(),	and then calls "compileClient()" on that.  This
	   results in a	code reference which will handle all client-server
	   SOAP	exchange.

	   The %options	available include all of the options for:

	   o   operation() (i.e. "service" and "port"),	and all	of

	   o   XML::Compile::SOAP::Operation::compileClient() (there are many
	       of these, for instance "transport_hook" and "server")

	   You cannot pass options for XML::Compile::Schema::compile(),	like
	   "<sloppy_integers ="	0>>, hooks or typemaps this way. Use
	   new(opts_rw)	and friends to declare those.

	   When	you use	compileCall(), the compiled code references get	cached
	   for you.  In	that case, you can use call() to use them.

	   example:

	     my	$call =	$wsdl->compileClient
	       ( operation => 'HelloWorld'
	       , port	   => 'PrefillSoap' # only required when multiple ports
	       );
	     my	($answer, $trace) = $call->($request);

	     # 'operation' keyword optional
	     my	$call =	$wsdl->compileClient('HelloWorld');

       $obj->namesFor($class)
	   Returns the list of names available for a certain definition	$class
	   in the WSDL.	See index() for	a way to determine the available
	   $class information.

       $obj->operation(	[$name], %options )
	   Collect all information for a certain operation.  Returned is an
	   XML::Compile::SOAP::Operation object.

	   An operation	is defined by a	service	name, a	port, some bindings,
	   and an operation name, which	can be specified explicitly and	is
	   often left-out: in the many configurations where there are no
	   alternative choices.	In case	there are alternatives,	you will be
	   requested to	pick an	option.

	    -Option	--Default
	     action	  <undef>
	     operation	  <required>
	     port	  <only	when just one port in WSDL>
	     server_type  undef
	     service	  <only	when just one service in WSDL>

	   action => STRING
	     Overrule the soapAction from the WSDL.

	   operation =>	NAME
	     Ignored when the parameter	list starts with a $name (which	is an
	     alternative for this option).  Optional when there	is only	one
	     operation defined within the portType.

	   port	=> NAME
	     Required when more	than one port is defined.

	   server_type => NAME
	     Overrules new(server_type).

	   service => QNAME|PREFIXED
	     Required when more	than one service is defined.

   Administration
       Extends "Administration"	in XML::Compile::Cache.

       $obj->declare($group, $component|ARRAY, %options)
	   Register specific compile %options for the specific $component. See
	   also	XML::Compile::Cache::declare().	The $group is either "READER",
	   "WRITER", "RW" (both	reader and writer), or "OPERATION".  As
	   $component, you specify the element name (for readers and writers)
	   or operation	name (for operations). %options	are specified as LIST,
	   ARRAY or HASH.

	   example:

	      $wsdl->declare(OPERATION => 'GetStockPrice', @extra_opts);
	      $wsdl->compileCalls;
	      my $answer = $wsdl->call(GetStockPrice =>	%request);

       $obj->doesExtend($exttype, $basetype)
	   Inherited, see "Administration" in XML::Compile::Schema

       $obj->elements()
	   Inherited, see "Administration" in XML::Compile::Schema

       $obj->findName($name)
	   Inherited, see "Administration" in XML::Compile::Cache

       $obj->findSchemaFile($filename)
       XML::Compile::WSDL11->findSchemaFile($filename)
	   Inherited, see "Administration" in XML::Compile

       $obj->importDefinitions($xmldata, %options)
	   Inherited, see "Administration" in XML::Compile::Schema

       $obj->knownNamespace($ns|PAIRS)
       XML::Compile::WSDL11->knownNamespace($ns|PAIRS)
	   Inherited, see "Administration" in XML::Compile

       $obj->namespaces()
	   Inherited, see "Administration" in XML::Compile::Schema

       $obj->types()
	   Inherited, see "Administration" in XML::Compile::Schema

       $obj->walkTree($node, CODE)
	   Inherited, see "Administration" in XML::Compile

   Introspection
       All of the following methods are	usually	NOT meant for end-users. End-
       users should stick to the operation() and compileClient() methods.

       $obj->endPoint(%options)
	   [2.20] Returns the address of the server, as	specified by the WSDL.
	   When	there are no alternatives for service or port, you not not
	   need	to specify those parameters.

	   The endpoint	in the WSDL is often wrong.  All compile functions
	   accept the "server" and "endpoint" parameters to overrule the
	   value.  With	"server", only the hostname:port is being replaced.
	   With	"endpoint", everything is replaced.

	    -Option --Default
	     port     <undef>
	     service  <undef>

	   port	=> NAME
	   service => QNAME|PREFIXED

	   example:

	    my $devel =	URI->new($wsdl->endPoint);
	    $devel->path('/sdk');
	    my $call = $wsdl->compileCall($opname, endpoint => $devel);

       $obj->explain($operation, $format, $direction, %options)
	   [2.13] Produce templates (see XML::Compile::Schema::template()
	   which detail	the use	of the $operation. Currently, only the "PERL"
	   template $format is available.

	   The $direction of operation is either "INPUT" (input	for the
	   server, hence to be produced	by the client),	or "OUTPUT" (from the
	   server, received by the client).

	   The actual work is done by
	   XML::Compile::SOAP::Operation::explain(). The %options passed to
	   that	method include "recurse" and "skip_header".

	   example:

	     print $wsdl->explain('CheckStatus', PERL => 'INPUT');

	     print $wsdl->explain('CheckStatus', PERL => 'OUTPUT'
		, recurse => 1		       # explain options
		, port	  => 'Soap12PortName'  # operation options
		);

	     foreach my	$op ($wsdl->operations)
	     {	print $op->explain($wsdl, PERL => 'INPUT');
	     }

       $obj->findDef( $class, <$qname|$prefixed|$name> )
	   With	a $qname, the HASH which contains the parsed XML information
	   from	the WSDL template for that $class-$name	combination is
	   returned.  You may also have	a $prefixed name, using	one of the
	   predefined namespace	abbreviations.	Otherwise, $name is considered
	   to be the localName in that class.  When the	$name is not found, an
	   error is produced.

	   Without $qname in SCALAR context, there may only be one such	name
	   defined otherwise an	error is produced.  In LIST context, all
	   definitions in $class are returned.

	   example:

	    $service  =	$obj->findDef(service => 'http://xyz');
	    @services =	$obj->findDef('service');

       $obj->index( [$class, [$qname]] )
	   With	a $class and $qname, it	returns	one WSDL definition HASH or
	   undef.  Returns the index for the $class group of names as HASH.
	   When	no $class is specified,	a HASH of HASHes is returned with the
	   CLASSes on the top-level.

	   $class includes "service", "binding", "portType", and "message".

       $obj->operations(%options)
	   Return a list with all operations defined in	the WSDL.

	    -Option	--Default
	     binding	  <undef>
	     port	  <undef>
	     server_type  undef
	     service	  <undef>

	   binding => NAME
	     Only return operations which use the binding with the specified
	     NAME.  By default,	all bindings are accepted.

	   port	=> NAME
	     Return only operations related to the specified port NAME.	 By
	     default operations	from all ports.

	   server_type => STRING
	     [3.06]

	   service => NAME
	     Only return operations related to the NAMEd service, by default
	     all services.

       $obj->printIndex( [$fh],	%options )
	   For available %options, see operations().  This method is useful to
	   understand the structure of your WSDL: it shows a nested list of
	   services, bindings, ports and portTypes.

	    -Option	  --Defined in	       --Default
	     show_declared  XML::Compile::Cache	 <true>

	   show_declared => BOOLEAN

DETAILS
       Extends "DETAILS" in XML::Compile::Cache.

   Distribution	collection overview
       Extends "Distribution collection	overview" in XML::Compile::Cache.

   Comparison
       Extends "Comparison" in XML::Compile::Cache.

   Collecting definitions
       Extends "Collecting definitions"	in XML::Compile::Cache.

   Addressing components
       Extends "Addressing components" in XML::Compile::Cache.

   Representing	data-structures
       Extends "Representing data-structures" in XML::Compile::Cache.

   Schema hooks
       Extends "Schema hooks" in XML::Compile::Cache.

   Typemaps
       Extends "Typemaps" in XML::Compile::Cache.

   Handling xsi:type
       Extends "Handling xsi:type" in XML::Compile::Cache.

   Key rewrite
       Extends "Key rewrite" in	XML::Compile::Cache.

   Initializing	SOAP operations	via WSDL
       When you	have a WSDL file, then SOAP is simple.	If there is no such
       file at hand, then it is	still possible to use SOAP.  See the DETAILS
       chapter in XML::Compile::SOAP.

       The WSDL	file contains operations which can be addressed	by name.  In
       the WSDL	file you need to find the name of the port to be used.	In
       most cases, the WSDL has	only one service, one port, one	binding, and
       one portType and	those names can	therefore be omitted.  If there	is a
       choice, then you	must explicitly	select one.

	use XML::Compile::WSDL11 ();

	# once in your program
	my $wsdl   = XML::Compile::WSDL11->new('def.wsdl');

	# XML::Compile::Schema refuses to follow "include" and
	# "import" commands, so	you need to invoke them	explicitly.
	# $wsdl->addWSDL('file2.wsdl');		   # optional
	# $wsdl->importDefinitions('schema1.xsd'); # optional

	# once for each	of the defined operations
	my $call   = $wsdl->compileClient('GetStockPrice');

	# see XML::Compile::SOAP chapter DETAILS about call params
	my $answer = $call->(%request);

DESCRIPTIONS
       Extends "DESCRIPTIONS" in XML::Compile::Cache.

SEE ALSO
       This module is part of XML-Compile-WSDL11 distribution version 3.06,
       built on	January	11, 2017. Website:
       http://perl.overmeer.net/xml-compile/

       Please post questions or	ideas to the mailinglist at
       http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile .	For
       live contact with other developers, visit the "#xml-compile" channel on
       "irc.perl.org".

LICENSE
       Copyrights 2014-2017 by [Mark Overmeer].	For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html

perl v5.24.1			  2017-01-11	       XML::Compile::WSDL11(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | DETAILS | DESCRIPTIONS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::Compile::WSDL11&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help