lib/CXGN/Search.pod

   1 =head1 NAME
   2
   3 CXGN::Search -  high-level framework for making powerful searches that all share
   4   the same interface, making it easy to integrate searches and learn to use ones
   5   written by others.
   6
   7 =head1 DESCRIPTION
   8
   9 A search implemented with this framework consists of a set of three objects:
  10 a Query, which encapsulates the parameters of a search, a Search, which knows
  11 how to actually execute the search and return the result set, and the Result,
  12 which is a 'page' of results from the total result set, with functions to
  13 iterate over the results, optionally turning pages for you automatically.
  14
  15 Pretty much any kind of search that can be expressed as this kind of process
  16 (that is, pretty much anything) can be implemented as a set of search
  17 framework subclasses.  The advantage of doing this is that the searches will
  18 all work the same way from the point of view of someone using them, meaning
  19 it's easier to integrate searches, or just use a new search you're not familiar
  20 with.
  21
  22 Also, if you use the popular search framework subclasses going along with
  23 L<CXGN::Search::DBI::Simple>, you can construct many kinds of powerful database
  24 searches that use Perl's L<DBI> and L<Class::DBI> with astonishingly little
  25 effort.
  26
  27 After you make your search, you may want to make it a nice web search,
  28 with automatically filling in forms, etc.  There are things you can
  29 subclass that will help you do this too, see L<CXGN::Search::WWWQuery>
  30 (for any kind of search), and L<CXGN::Search::DBI::Simple::WWWQuery>
  31 (more specialized functionality for database searches).
  32
  33 =head1 USING SEARCHES
  34
  35 Using a search that's been written for the search framework is drop-dead
  36 easy, which is the whole point.  Here's how to use BogoPeopleSearch, which
  37 happens to be a database search done with L<CXGN::Search::DBI::Simple>.
  38
  39   use CXGN::BogoPeopleSearch;
  40
  41   #find all the people whose last name begins with J
  42   my $search = CXGN::BogoPeopleSearch->new;
  43   my $query = $search->new_query;
  44   $query->last_name("LIKE 'J%'");
  45   my $results = $search->do_search($query);
  46
  47   #print them all out
  48   print "In all, ",$results->total_results,
  49         " people have a last name beginning with J:\n";
  50   while( my $person = $results->next_result ) {
  51     print "  ",$person->[1]," ",$person->[2],"\n";
  52   }
  53
  54 And that, as they say, is that.
  55
  56 =head1 CREATING SEARCHES
  57
  58 This document just describes the overarching structure of a search framework
  59 search, that is, it consists of three objects, and you feed the query to the
  60 search and get back a result.  This alone doesn't make implementing a search
  61 any faster or easier, it just gives you a specification for its interface.
  62
  63 For making it easier to implement specific types of searches, like database
  64 searches, BLAST searches, or whatever, there are partial implementations
  65 you can subclass:
  66
  67   L<CXGN::Search::DBI::Simple>
  68   L<CXGN::Search::DBI::CDBI> (a subclass of Simple that adds optimizations for returning Class::DBI objects)
  69
  70 =head1 INHERITANCE HIERARCHY
  71
  72 see L<http://internal.sgn.cornell.edu/docs/search/inheritance_diagram.pdf>
  73
  74 =head1 INTERFACES (ABSTRACT CLASSES)
  75
  76   L<CXGN::Search::SearchI>
  77   L<CXGN::Search::QueryI>
  78   L<CXGN::Search::ResultI>
  79
  80 =head1 SEARCH IMPLEMENTATIONS
  81
  82   L<CXGN::Unigene::Search> - low complexity
  83   L<CXGN::Genomic::Search::GSS> - medium complexity
  84   L<CXGN::Genomic::Search::Clone> - high complexity
  85
  86 =head1 AUTHOR(S)
  87
  88   Robert Buels - rmb32@cornell.edu
  89
  90 =cut
  91