The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Context-0.968
River stage one • 2 direct dependents • 2 total dependents
3 ++
/ App::quickstart

NAME

App::quickstart - App::Context Developer's Quick-Start Guide

INTRODUCTION

This is the Developer's Quickstart Guide to the App::Context Framework. Its focus is to give a minimum amount of theoretical or explanatory background and get right into learning by example.

DOCUMENTATION OVERVIEW

That having been said, it is also important to let you know what documentation exists and what state it is in.

I got started building the App::Context framework a while ago. The documentation is very limited. This is an effort to bring it all together. This list shows how all of the documentation fits together and in what state it is.

PURE DOCUMENTATION

The following documentation is in good shape. To get started, read them more or less in the order shown.

The following documentation also is in good shape. It is background reference material.

The following documentation is in a state that needs review, modification, or completion.

CLASS/MODULE DOCUMENTATION (indented entries are subclasses)

Most of this documentation needs review, modification, and completion.

INSTALLATION

You can go through one of the installation guides. Installing the App::Context Framework generally involves several distributions and should just work when installed from CPAN.

  perl -MCPAN -e shell
  cpan> install App::Options
  cpan> install App::Context
  cpan> install App::Repository
  cpan> install App::Widget
  cpan> exit

If it's not this easy, I need to work on making it easier. Please let me know (spadkins@gmail.com) and I'll fix it.

QUICK START TO COMMAND LINE DATABASE PROGRAMS

One of the big advantages of using the App::Context Framework for command-line programs is in developing a suite of database programs (particularly for a MySQL database).

Choose a root directory for your system, assigning it to the PREFIX variable.

vi ~/.bash_profile

  export PREFIX=/usr/mycompany/prod

vi $PREFIX/etc/app.conf

  dbhost  = localhost
  dbname  = test
  dbuser  = scott
  dbpass  = tiger

vi $PREFIX/etc/app.pl

  $conf = {
    Repository => {
      default => { alias => "db", },
      db => {
        class => "App::Repository::MySQL",
      },
    },
  };

vi $PREFIX/bin/prog

  #!/usr/bin/perl -w
  use strict;
  use App::Options (
      options => [qw(dbhost dbname dbuser dbpass)],
      option => {
          dbhost => {
              description => "database host",
              required => 1,
          },
          dbname => {
              description => "database name",
              required => 1,
          },
          dbuser => {
              description => "database user",
              required => 1,
          },
          dbpass => {
              description => "database password",
              required => 1,
          },
      },
  );
  use App;
  use App::Repository;
  {
      my $context = $App->context();
      my $db = $context->repository();
      # perform database ops like ...
      # my $rows = $db->get_rows("customer", { last_name => "Smith" }, ["first_name", "last_name", "birth_dt"]);
      # my $hashes = $db->get_hashes("customer", { "birth_dt.le" => "2000-01-01" }, ["first_name", "last_name", "birth_dt"]);
      # my $age = $db->get("customer", { customer_id => 45 }, "age");
  }

The best parts about writing database programs with App::Repository in the App::Context framework is that all of your programs get automatic SQL debugging, timing, and explaining.

  prog --debug_sql      # show all SQL statements and their timings
  prog --debug_sql=2    # show all SQL statements and their timings and all rows returned from selects
  prog --debug_sql --explain_sql   # show SQL statements and explain them

See App::Options, App::Repository::quickstart, and App::Repository::devguide for more info on this.

QUICK START TO OBJECT-ORIENTED COMMAND LINE PROGRAMS

Another of the big advantages of using the App::Context Framework for command line programs is in developing programs which use and operate on Business Objects (the object-oriented analysis concept, not the commercial reporting software).

Many "object-oriented" programs are written without ever using a true Business Object. The reason for this is that the issues of maintaining object state are so tricky that people rarely get around to using Business Objects in their command line programs.

Business Objects come in two types: Business Entity Objects and Business Process Objects. Business Entity Objects represent things in the business realm: Customer, Store, Employee, Product, PurchaseOrder. Business Process Objects are those objects that model business processes.

The following abstractions exist in order to subclass for your business objects. As you get into using them, you will learn when to use which one, and you will find that there is of course more than one way to do it.

  • App::RepositoryObject - An object whose state is shared across multiple sessions as a single row in a database (repository). These are generally the Business Entity Objects.

  • App::SessionObject - A named object whose state is maintained throughout the session. These are generally the Business Process Objects.

  • App::SessionObject::RepositoryObjectSet - A named object with session state and shared state consisting of a set of rows from a single table in a database (repository).

  • App::SessionObject::RepositoryObjectDomain - A named object with session state and shared state consisting of a set of related sets of rows from multiple tables in a database (repository).

The big advantage of writing object-oriented programs is for code reuse. Whenever someone whips up a perl script to do some processing on the system, that programming logic is unavailable for use in any other program (such as an interactive web application).

One way to cure this is to have an App::SessionObject where all of the logic for a command line program is implemented as a single method call.

The choice of how many SessionObjects to use for all of the logic is a matter of preference. You could put all this logic on one kitchen-sink-style SessionObject or you could group the functions into like types and put them on different SessionObjects. You may wish to have these SessionObject take on the responsibilities of different "roles" played by members of the organization or tasks performed by different departments. These can easily be reorganized later. The important thing is to get the logic out of the command line programs and into objects so that the logic can be reused later.

When viewed in this light, the command line program only becomes a user interface for a method call provided by a SessionObject. The easy way to start is just to pass the %App::options hash (shown below). However, in many cases the program will do a few more steps to make a more natural call to the SessionObject's method.

EXAMPLES

vi $PREFIX/etc/app.pl

  $conf = {
    Repository => {
      default => { alias => "db", },
      db => {
        class => "App::Repository::MySQL",
      },
    },
    SessionObject => {
      credit_manager => {
        class => "App::SessionObject::CreditManager",
      },
    },
  };

vi $PREFIX/lib/App/SessionObject/CreditManager.pm

  use App;
  use App::Repository;
  package App::SessionObject::CreditManager;
  $VERSION = "0.50";
  @ISA = ("App::SessionObject");
  use strict;

  sub check_customer_credit {
      my ($self, $options) = @_;
      my $customer_id = $options->{customer_id} || die "No customer ID provided";
      my $context = $self->{context};   # every Service has a reference to its Context
      my $db = $context->repository();  # get the default repository from the Context

      # There must be a table named customer with primary key of "customer_id" and
      # at least the columns "approval_ind char(1)", "denial_msg varchar(255)",
      # "first_name varchar(255)", and "last_name varchar(255)".
      my $customer = $db->get_object("customer", $customer_id);  # returns an App::RepositoryObject

      my ($approval_ind, $denial_msg);

      # ... do some processing ...
      if ($customer->{first_name} eq "Bill" && $customer->{last_name} eq "Gates") {
          $approval_ind = "N";
          $denial_msg = "Too rich";
      }
      else {
          $approval_ind = "N";
      }

      if ($approval_ind eq "Y") {
          $customer->set("approval_ind",$approval_ind);
          print "Customer $customer_id approved.\n";
      }
      else {
          $customer->set(["approval_ind","denial_msg"],[$approval_ind,$denial_msg]);
          print "Customer $customer_id denied: $denial_msg.\n";
      }
  }

  1;

vi $PREFIX/bin/check_customer_credit

  #!/usr/bin/perl -w
  # NOTE: All of this code is about the User Interface to the logic.
  #       The logic itself is hidden away in "App::SessionObject::CreditManager".
  use strict;
  use App::Options (
      options => [qw(dbhost dbname dbuser dbpass customer_id)],
      option => {
          dbhost => {
              description => "database host",
              required => 1,
          },
          dbname => {
              description => "database name",
              required => 1,
          },
          dbuser => {
              description => "database user",
              required => 1,
          },
          dbpass => {
              description => "database password",
              required => 1,
          },
          customer_id => {
              description => "the ID of the customer to check",
              required => 1,
              type => "integer",
          },
      },
  );
  use App;
  use App::Repository;
  {
      my $context = $App->context();
      my $db = $context->repository();
      my $credit_manager = $context->session_object("credit_manager");
      $credit_manager->check_customer_credit(\%App::options);
  }

QUICK START TO WEB PROGRAMS

A web program is simply choosing a widget to display on the browser. Widgets may be arbitrarily complex, containing other widgets, and so taking the form of an entire web application. Since any widget can be viewed in a browser, additional widgets may be developed and debugged before they are integrated into a larger applications.

Widgets (App::Widget) are simply SessionObject's with an html() method which allows them to be viewed nicely by a web browser. They maintain their state throughout the duration of the session.