#!/usr/local/bin/perl -w

BEGIN {
    $VERSION = do { my @r=(q$Revision: 123 $=~/\d+/g); $r[0]; };
}

use strict;

use App::Options (
    args_description => "[files] ( .tests/.scenario/.xml files in \$PREFIX/share/ota/(tests|scenario|xml) )",
    options => [qw(server dirs default_ota_release minimal xmlns schema_location validation verbose)],
    option => {
        server => {
            description => "Name of a configured remote server to send the Request to and get a Response from",
            default => "default",
        },
        dirs => {
            description => "Directory for OTA messages to send",
            default => '${prefix}/share/ota/tests:${prefix}/share/ota/scenario:${prefix}/share/ota/xml',
        },
        default_ota_release => {
            description => "The default OTA specification release (i.e. 2005B, 2006A, etc.)",
            default => "2006B",
        },
        minimal => {
            description => "Use minimal number of HTTP Headers",
            default => 0,
        },
        xmlns => {
            description => "XML namespace for OTA documents",
            default => "http://www.opentravel.org/OTA/2003/05",
        },
        schema_location => {
            description => "directory (URL) of schemas for validation",
            default => '${prefix}/share/ota/2006B',
        },
        validation => {
            description => "use strict validation for all document parsing (0=well-formed-only, 1=validated)",
            default => 1,
        },
        verbose => {
            description => "Print more detail (0=silent,1=response-xmls,2=all-xmls,3=protocol-info,4=debug)",
            default => 0,
        },
    },
);
use App;

use Business::Travel::OTA;

=head1 NAME

otaclient - Submits OTA messages to an OTA-conformant server

=head1 SYNOPSIS

  otaclient
  otaclient OTA_Ping.scenario
  otaclient --verbose OTA_Ping.scenario
  otaclient OTA_PingRQ.xml
  otaclient /usr/mycompany/prod/share/ota/xml/OTA_PingRQ.xml

=head1 DESCRIPTION

With no other options given on the command line, the "otaclient" command will
read the default set of tests configured for it, sumbit messages as appropriate
to the configured server, and print out a report card with the results of the
tests. 

This is useful for exercising (and testing) an OTA-conformant server that you have developed.

In general, this command iterates over the list of files given as arguments.
If none are given, then the file "default.tests" is run.

=head1 FILE TYPES

There are three kinds of files that the "otaclient" command can process.

  *.tests
  *.scenario
  *.xml

=head2 XML Files (*.xml)

Processing an XML file (*.xml) is the most straighforward.
It simply reads an XML file, submits it to the servers, and receives a response.
This is an important baseline capability.

The contents of an XML file would be any valid XML (presumably an OTA message)
such as the following.

 <?xml version="1.0" encoding="UTF-8"?>
 <OTA_PingRQ
     xmlns="http://www.opentravel.org/OTA/2002/08"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.opentravel.org/OTA/2002/08 /usr/rubicon/spadkins/src/OTA/Business-Travel-OTA/schemas/2002A/OTA_PingRQ.xsd"
     TimeStamp="2002-12-03T11:09:47-05:00"
     Target="Production"
     Version="2002A"
     SequenceNmbr="1" >
   <EchoData>Are you there?</EchoData>
 </OTA_PingRQ>

=head2 Scenario Files (*.scenario)

A Scenario file (*.scenario) presents an intelligent wrapper around a simple
XML transfer that makes this much more useful.
With a scenario file, you can

 * specify a sample XML file as a "template" and then perform parameter
   substitution.  The actual XML message that is sent might have a different
   arrival date, flight number, property code, or city station code (etc.)
   from the "template" message.
 * set up a sequence of message exchanges where values from one message are
   copied into the next message to be sent.
 * perform tests along the way to ensure that the returned messages and
   the values in them are according to your expectations.

The contents of a Scenario File is something like the following.

 VALIDATION      ON
 INCLUDE         defaults.scenario
 DOCUMENT        OTA_PingRQ.xml
 DOCUMENT        [rs]                            = OTA_PingRS.xml
 DOCUMENT        [rq]                            = [current]
 DEFAULT         CONVERSATION{Target}            = Production
 DEFAULT         CONVERSATION{Version}           = 2004A
 DEFAULT         CONVERSATION{SequenceNmbr}      = 1
 SET             CONVERSATION{current_datetime}  = SYSTEM{current_datetime}
 SET             /OTA_PingRQ/@TimeStamp          = CONVERSATION{current_datetime}
 SET             /OTA_PingRQ/@Target             = CONVERSATION{Target}
 SET             /OTA_PingRQ/@Version            = CONVERSATION{Version}
 SET             /OTA_PingRQ/@SequenceNmbr       = CONVERSATION{SequenceNmbr}
 SET             /OTA_PingRQ/EchoData            = Hello world!
 DOCUMENT[rq]
 SEND
 TEST            ROOT-ELEMENT                    =  OTA_PingRS
 TEST            /OTA_PingRQ/@xmlns              =  http://www.opentravel.org/OTA/2002/08
 TEST            /OTA_PingRQ/@xmlns:xsi          =  http://www.w3.org/2001/XMLSchema-instance
 TEST            /OTA_PingRQ/@xsi:schemaLocation =~ "^http://www.opentravel.org/OTA/2002/08 "
 TEST            /OTA_PingRQ/@TimeStamp          >= CONVERSATION{current_datetime}
 TEST            /OTA_PingRQ/@TimeStamp          <= SYSTEM{current_datetime}
 TEST            /OTA_PingRQ/@Target             =  CONVERSATION{Target}
 TEST            /OTA_PingRQ/@Version            =  CONVERSATION{Version}
 TEST            /OTA_PingRQ/@SequenceNmbr       =  CONVERSATION{SequenceNmbr}
 TEST            /OTA_PingRQ/EchoData            = Hello world!

=head2 Tests Files (*.tests)

A Tests file (*.tests) describes a sequence of *.tests, *.scenario, and *.xml
files which should be run.  All of the tests in all of them are accumulated
and printed out on the final report card.

The contents of a Tests File is something like the following.

 FILE OTA_PingRQ.xml
 FILE OTA_Ping-0001.scenario

Raw XML files are not very useful because there are no defined tests and no parameterization.
Generally, a Tests File is full of Scenario Files (which contains the tests which get
accumulated for the report card) and other Tests Files.

=head1 INSTALLATION

=head1 CONFIGURATION AND COMMAND LINE OPTIONS

The "otaclient" program may be configured by all the means provided for by the
configuration system it uses called "App::Options."

  man App::Options
  perldoc App::Options

Furthermore, the "otaclient" program and the classes in the Business::Travel::OTA
distribution are built on the App-Context Framework (whose documentation is currently
not in good order).  Information will be provided here with regard to the items
necessary to know.

Specifically, this means that if you have installed your the Business::Travel::OTA
software under $HOME (i.e. Unix) or "C:\usr" (i.e. Windows), you would set an environment
variable, $PREFIX, to that base directory.

If this PREFIX variable were set to /home/mikesmith,
then the following section might appear in the "$PREFIX/etc/app/app.conf" file.

 [otaclient]
 prefix           = /home/mikesmith
 perlinc          = /home/mikesmith/lib/perl5/5.8.4 /home/mikesmith/lib/perl5/5.8.4/i686-linux /usr/local/lib/perl5/site_perl/5.8.4 /home/mikesmith/lib/perl5/site_perl/5.8.4 /home/mikesmith/lib/perl5/site_perl/5.8.4/i686-linux /home/mikesmith/lib
 server           = default
 server_url       = http://localhost/cgi-bin/mikesmith/otaserver
 dirs             = ${prefix}/share/ota/tests:${prefix}/share/ota/scenario:${prefix}/share/ota/xml
 default_ota_release = 2006B
 transport_class  = Business::Travel::OTA::Transport::HTTP
 minimal          = 0
 conf_file        = ${prefix}/etc/app/ota.pl
 # verbose: Print more detail (0=silent,1=response-xmls,2=all-xmls,3=protocol-info,4=debug)
 verbose          = 4

As with all App::Options-enabled programs, these variables can be set in the options
file (app.conf) and overridden in a more specific options file, in an environment variable
or on the command line.

=head1 SEARCH PATHS

The "otaclient" program looks for all relative filenames in a list of directories which
is configurable with the "dirs" option.  The default is to look for all *.xml, *.scenario,
and *.tests files in the following directories.

 $PREFIX/share/ota/xml
 $PREFIX/share/ota/scenario
 $PREFIX/share/ota/tests

=cut

{
    my $context = App->context();
    my $client  = $context->client();
    $client->run(@ARGV);
}

=head1 ACKNOWLEDGEMENTS

 * Author:  Stephen Adkins <sadkins@therubicongroup.com>
 * Copyright: (c) 2005 Stephen Adkins (for the purpose of making it Free)
 * License: This is free software. It is licensed under the same terms as Perl itself.

=head1 SEE ALSO

=cut

