Martin Kutter > SOAP-WSDL-2.00.99_3 > SOAP::WSDL::Generator::Visitor

Download:
SOAP-WSDL-2.00.99_3.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  20
Open  19
View/Report Bugs
Module Version: v2.0.99_3   Source   Latest Release: SOAP-WSDL-v3.002

NAME ^

SOAP::WSDL::Generator::Visitor - SOAP::WSDL's Visitor-based Code Generator

DESCRIPTION ^

SOAP::WSDL features a code generating facility. This code generation facility (in fact there are several of them) is implemented as Visitor to SOAP::WSDL::Base-derived objects.

The Visitor Pattern

The Visitor design pattern is one of the object oriented design pattern described by [GHJV1995].

A Visitor is an object implementing some behaviour for a fixed set of classes, whose implementation would otherwise need to be scattered accross those classes' implementations.

Visitors are usually combined with Iterators for traversing either a list or tree of objects.

A Visitor's methods are called using the so-called double dispatch technique. To allow double dispatching, the Visitor implements one method for every class to be handled, whereas every class implements just one method (commonly named "access"), which does nothing more than calling a method on the reference given, with the self object as parameter.

If all this sounds strange, maybe an example helps. Imagine you had a list of person objects and wanted to print out a list of their names (or address stamps or everything else you like). This can easily be implemented with a Visitor:

    package PersonVisitor;
    use Class::Std;    # handles all basic stuff like constructors etc.

    sub visit_Person {
        my ( $self, $object ) = @_;
        print "Person name is ", $object->get_name(), "\n";
    }

    package Person;
    use Class::Std;
    my %name : ATTR(:name<name> :default<anonymous>);

    sub accept { $_[1]->visit_Person( $_[0] ) }

    package main;
    my @person_from = ();
    for (qw(Gamma Helm Johnson Vlissides)) {
        push @person_from, Person->new( { name => $_ } );
    }

    my $visitor = PersonVisitor->new();
    for (@person_from) {
        $_->accept($visitor);
    }

    # will print
    Person name is Gamma
    Person name is Helm
    Person name is Johnson
    Person name is Vlissides

While using this pattern for just printing a list may look a bit over-sized, it may become handy if you need multiple output formats and different classes to operate on.

The main benefits using visitors are:

Of course, there are also drawbacks in the visitor pattern:

Visitors are usually accompanied by a Iterator. The Iterator may be implemented in the visited classes, in the Visitor, or somewhere else (in the example it was somewhere else).

The Iterator decides which object to visit next.

Why SOAP::WSDL uses the Visitor pattern for Code Generation

Code generation in SOAP::WSDL means generating various artefacts:

All these behaviours could well be (and have historically been) implemented in the classes holding the WSDL data. This made these classes rather bloated, and made it hard to change behaviour (like supporting SOAP Headers, supporting atomic types, and other features which were missing from early versions of SOAP::WSDL).

Implementing these behaviours in Visitor classes eases adding new behaviours, and reducing the incompletenesses still inherent in SOAP::WSDL's WSDL and XML schema implementation.

Implementation

accept

SOAP::WSDL::Base defines an accept method which expects a Visitor as only parameter.

The method visit_Foo_Bar is called on the visitor, with the self object as parameter.

The actual method name is constructed this way:

Example:

When visiting a SOAP::WSDL::XSD::ComplexType object, the method visit_XSD_ComplexType is called on the visitor.

Writing your own visitor

SOAP::WSDL eases writing your own visitor. This might be required if you need some special output format from a WSDL file or want to feed your own serializer/deserializer pair with custom configuration data. Or maybe you want to generate C# code from it...

To write your own code generating visitor, you should subclass SOAP::WSDL::Generator::Visitor. It implements (empty) default methods for all SOAP::WSDL data classes:

In your Visitor, you must implement visit_Foo methods for all classes you wish to visit.

The SOAP::WSDL::Generator::Visitor implementations include part of their own Iterator (which means they know how to find the next objects to visit). You may or may not choose to implement a separate Iterator.

Letting a visitor implementing its own Iterator visit a WSDL definition is as easy as writing something like this:

 my $visitor = MyVisitor->new();
 my $parser = SOAP::WSDL::Expat::WSDLParser->new();
 my $definitions = $parser->parse_file('my.wsdl'):

 $definitions->_accept( $visitor );

If you need an iterator following the somewhat crude path of dependencies in a WSDL1.1 definition, you might want to look at SOAP::WSDL::Generator::Iterator::WSDL11.

REFERENCES ^

LICENSE AND COPYRIGHT ^

Copyright 2004-2008 Martin Kutter.

This file is part of SOAP-WSDL. You may distribute/modify it under the same terms as perl itself

AUTHOR ^

Martin Kutter <martin.kutter fen-net.de>

REPOSITORY INFORMATION ^

 $Rev: 391 $
 $LastChangedBy: kutterma $
 $Id: Client.pm 391 2007-11-17 21:56:13Z kutterma $
 $HeadURL: https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Client.pm $
syntax highlighting: