1# ====================================================================== 2# 3# Copyright (C) 2000-2003 Paul Kulchenko (paulclinger@yahoo.com) 4# SOAP::Lite is free software; you can redistribute it 5# and/or modify it under the same terms as Perl itself. 6# 7# $Id: Schema.pm,v 1.5 2004/11/14 19:30:49 byrnereese Exp $ 8# 9# ====================================================================== 10 11=pod 12 13=head1 NAME 14 15SOAP::Schema - provides an umbrella for the way in which SOAP::Lite manages service description schemas 16 17=head1 DESCRIPTION 18 19This class provides an umbrella for the way in which SOAP::Lite manages service description schemas. Currently, the only support present is for the Web Services Description Language (WSDL). This is another of the classes not generally designed to be directly instantiated by an application, though it can be if so desired. 20 21=head1 METHODS 22 23=over 24 25=item new(optional key/value pairs) 26 27 $schema = SOAP::Schema->new(parse => $schema_uri); 28 29This is the class constructor. With no arguments, it creates a blank object of the class. Any arguments that are passed are treated as key/value pairs in which the key represents one of the methods described here, and the value is what gets passed when the method itself gets invoked. 30 31=item parse(service description URI) 32 33 $schema->parse('http://schemas.w3.org/soap.wsdl'); 34 35Parses the internal representation of the service description prior to the generation of stub routines to provide method-like access to the remote services. 36 37=item access(service description URI) 38 39 $schema->access('http://soap.org/service.wsdl'); 40 41Loads the specified service description from the given URL, using the current value of the schema accessor if none is provided. The full content of the URL is returned on success, or an exception is thrown (via C<die>) on error. 42 43=item load 44 45 $schema->load; 46 47Takes the internal representation of the service and generates code stubs for the remote methods, allowing them to be called as local object methods. Stubs are generated for all the functions declared in the WSDL description with this call because it's enough of a class framework to allow for basic object creation for use as handles. 48 49=item schema 50 51 $current_schema = $schema->schema; 52 53Gets (or sets) the current schema representation to be used by this object. The value to be passed when setting this is just the URI of the schema. This gets passed to other methods such as access for loading the actual content. 54 55=item services 56 57 $hashref = $schema->services; 58 59Gets or sets the services currently stored on the object. The services are kept as a hash reference, whose keys and values are the list of returned values from the WSDL parser. Keys represent the names of the services themselves (names have been normalized into Perl-compatible identifiers), with values that are also hash references to the internal representation of the service itself. 60 61=item stub 62 63Returns the autogenerated Perl code as a string. This code is generated from the WSDL provided by the C<service> method call. The code contains a package definition for the service being called. 64 65 my $client = SOAP::Lite->new; 66 my $code = $client->service($WSDL_URL)->stub; 67 open FILE,">ServicePackage.pm"; 68 print FILE $code; 69 close FILE; 70 71=item cache_dir 72 73Sets/retrieves the value of the directory where generated stubs will be cached. If C<cache_dir> is null, then no caching will be performed. 74 75 my $client = SOAP::Lite->new; 76 my $code = $client->cache_dir("/tmp")->service($WSDL_URL)->stub; 77 78If C<cache_dir> is undefined, no caching will take place. 79 80=item cache_ttl 81 82Sets/retrieves the value of the time to live (in seconds) for cached files. This is only relevant when used in conjunction with C<cache_dir>. 83 84If C<cache_ttl> is set to 0, the cache will never expire. Files will have to be removed manually in order for the cache to be refreshed. 85 86 my $client = SOAP::Lite->new; 87 my $code = $client->cache_ttl(3600)->cache_dir("/tmp")->service($WSDL_URL)->stub; 88 89The default time to live is 0. 90 91=item useragent(LWP::UserAgent) 92 93 my $client = SOAP::Lite->new; 94 $ua = $client->schema->useragent; 95 $ua->agent("Fubar! 0.1"); 96 my $response = $client->service("http://localhost/some.wsdl") 97 ->someMethod("Foo"); 98 99Gets or sets the classes UserAgent used for retrieving schemas over the web. 100This allows users to have direct access to the UserAgent so that they may control 101the credentials passed to a remote server, or the specific configuration of their 102HTTP agent. 103 104=back 105 106=head1 SOAP::Schema::WSDL 107 108At present, the SOAP::Lite toolkit supports only loading of service descriptions in the WSDL syntax. This class manages the parsing and storing of these service specifications. As a general rule, this class should be even less likely to be used directly by an application because its presence should be completely abstracted by the previous class (SOAP::Schema). None of the methods are defined here; the class is only mentioned for sake of reference. 109 110=head1 ACKNOWLEDGEMENTS 111 112Special thanks to O'Reilly publishing which has graciously allowed SOAP::Lite to republish and redistribute large excerpts from I<Programming Web Services with Perl>, mainly the SOAP::Lite reference found in Appendix B. 113 114=head1 COPYRIGHT 115 116Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved. 117 118This library is free software; you can redistribute it and/or modify 119it under the same terms as Perl itself. 120 121=head1 AUTHORS 122 123Paul Kulchenko (paulclinger@yahoo.com) 124 125Randy J. Ray (rjray@blackperl.com) 126 127Byrne Reese (byrne@majordojo.com) 128 129=cut 130 131 132 133 134 135