/ 
MOSES-MOBY-0.96.1
River stage zero No dependents
/ MOSES::MOBY::Parser

NAME

MOSES::MOBY::Parser - parser of XML BioMoby messages

SYNOPSIS use MOSES::MOBY::Parser;

# create a parser
my $parser = new MOSES::MOBY::Parser ();

# parse a file $package is a MOSES::MOBY::Pacakge reference
my $package = $parser->parse ( method => 'file', data => "/home/moby/input.xml" );

# parse a string of xml
$package = $parser->parse ( method => 'string', data => $inputXML );

DESCRIPTION

The MOSES::MOBY::Parser is a SAX based parser used to parse BioMOBY service XML messages.

The Moby::Parser is able to read Biomoby service/client XML data, parse the XML and create from them an instance of Moby::Package. The parser can be invoked by using the subroutine parse.

The parser depends on generated Perl modules that define all of the Biomoby data types. There is a generator MOSES::MOBY::Generators::GenTypes that produces such modules into a package MOSES::MOBY::Data.

There is one situation when the parser tries to substitute an unknown data type by a known one. If the parsing encoutered an XML tag depicting a top-level data object (not a member object of some other data object) and if there is no class available for such object, the parser can be instructed to create a substituted object whose name was given in the parser constructor. This is to prevent situation when a long-time running and deployed service suddenly gets a request from a client that uses more up-to-date list of data types. It would be bad to let such service die (or minimally respond unproperly) just because its modules were generated too long ago.

Because also skeletons for services can be generated, it is easy to ensure that a service knows its "the most specialized" data type it can still served, and that it passes it to the parser constructor.

If the parser finds an unknown object/tag but no substitute was passed in the parser constructor, it prints a warning and ignores the whole object, with all its descendants.

The parser also produces a warning if it makes the substitution described above. Both these warnings should signal that new data types should be generated, and services restarted. Fortunately, it does not happen often at all.

Be aware, however, that this substitution may do a wrong thing if there are more bad top-level objects - such as in case when a result has more outputs.

If the parser finds another problem, usually related to the invalid XML, it raises an Exception with error message containing line and column close to place where the error happened (Not yet, but soon).

One possible problem would be when article names of the member data types in the parsed XML do not correspond what was registered in the Biomoby registry. Parser spots it and stops parsing (because it does not know where to put this member object).

You can test parser by using a simple testing-parser.pl client. This is how to invoke it and how to get its help:

src/scripts/testing-parser.pl -h

Sample input is located in the 'data' directory.

All XML tags and all attribute names that are recognized and processed by this parser are stored as constants in the module Moby::Tags

ACCESSIBLE ATTRIBUTES

Details are in MOSES::MOBY::Base. Here just a list of them:

cachedir
registry
lowestKnownDataTypes

SUBROUTINES

new

Create a Parser object. The only argument to this method is

lowestKnownDataTypes => { $input_name => $known_type }.

The purpose of lowestKnownDataTypes is mentioned above in the Description. After constructing a parser, use the 'parse' subroutine.

parse

Creates a MOSES::MOBY::Package object based on the input XML. This is the only sub that should be used in this module as the most of the other subroutines in this module implement the SAX interface or are used by the subroutines that implement the SAX interface.

parse has the following arguments: args: method => 'string', data => direct XML OR method => 'file', data => filename

AUTHORS, COPYRIGHT, DISCLAIMER

Edward Kawas (edward.kawas [at] gmail [dot] com)
Martin Senger (martin.senger [at] gmail [dot] com)

Copyright (c) 2006 Martin Senger, Edward Kawas. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This software is provided "as is" without warranty of any kind.