Astro::Catalog::Transport::REST - A base class for REST query modules

  use base qw/ Astro::Catalog::Transport::REST /;

package Astro::Catalog::Transport::REST;

# L O A D   M O D U L E S --------------------------------------------------

use 5.006;
use strict;
use warnings;
use warnings::register;
use base qw/ Astro::Catalog::Query /;
use vars qw/ $VERSION /;

use LWP::UserAgent;
use Net::Domain qw(hostname hostdomain);
use File::Spec;
use Carp;

# generic catalog objects
use Astro::Catalog;
use Astro::Catalog::Star;

'$Revision: 1.7 $ ' =~ /.*:\s(.*)\s\$/ && ($VERSION = $1);

sub new {
  my $proto = shift;
  my $class = ref($proto) || $proto;

  # bless the query hash into the class
  my $block = bless { OPTIONS   => {},
		      COORDS    => undef,
                      URL       => undef,
                      QUERY     => undef,
                      USERAGENT => undef,
                      BUFFER    => undef }, $class;

  # Configure the object [even if there are no args]
  $block->configure( @_ );

  return $block;

}

sub useragent {
  my $self = shift;
  if (@_) {
     my $ua = shift;
     croak "Must be a LWP::UserAgent"
       unless UNIVERSAL::isa($ua, "LWP::UserAgent");
     $self->{USERAGENT} = $ua;
   } else {
     # If we have no UA but we have requested one, create it ourself
     # This overcomes a chicken and egg situation if a subclass
     # wants to go out on the net during object instantiation
     # before configure() has been called

     # Setup the LWP::UserAgent
     my $ua = new LWP::UserAgent( timeout => 30 );

     $self->useragent( $ua );
     $ua->agent( $self->_default_useragent_id );

     # Grab Proxy details from local environment
     $ua->env_proxy();

   }
  return $self->{USERAGENT};
}

sub querydb {
  my $self = shift;

  # call the private method to make the actual query
  $self->_make_query();

  # check for failed connect
  return undef unless defined $self->{BUFFER};

  # return catalog
  return $self->_parse_query();

}

sub proxy {
   my $self = shift;

   # grab local reference to user agent
   my $ua = $self->useragent;

   if (@_) {
      my $proxy_url = shift;
      $ua->proxy('http', $proxy_url );
   }

   # return the current proxy
   return $ua->proxy('http');

}

sub timeout {
   my $self = shift;

   # grab local reference to user agent
   my $ua = $self->useragent;

   if (@_) {
      my $time = shift;
      $ua->timeout( $time );
   }

   # return the current timeout
   return $ua->timeout();

}

sub query_url {
  my $self = shift;
  if (@_) {
    $self->{QUERY} = shift;
  }
  if (defined $self->{QUERY}) {
    return $self->{QUERY};
  } else {
    return "http://". $self->url .
      "/" . $self->_default_url_path;
  }

  return $self->{QUERY};
}

sub url {
  my $self = shift;

  # SETTING URL
  if (@_) { 

    # set the url option
    my $base_url = shift;
    $self->{URL} = $base_url;
    if( defined $base_url ) {
       $self->query_url("http://$base_url/" .
			$self->_default_url_path );
    }
  }

  # RETURNING remote host
  if (defined $self->{URL}) {
    return $self->{URL};
  } else {
    return $self->_default_remote_host();
  }
}

sub agent {
  my $self = shift;
  return $self->useragent->agent();
}

sub _default_remote_host {
  croak "default remote host must be specified in subclass\n";
}

sub _default_url_path {
  croak "default url path information must be subclassed\n";
}

sub _default_useragent_id {
  my $self = shift;
  my $HOST = hostname();
  my $DOMAIN = hostdomain();
  my $package = ref($self);
  my $pack_version;
  {
    # Need a symbolic reference
    no strict 'refs';
    $pack_version = ${ $package."::VERSION" };
  }
  $pack_version = 'UNKNOWN' unless defined $pack_version;
  return "Astro::Catalog::REST/$pack_version ($HOST.$DOMAIN)";
}

sub _make_query {
   my $self = shift;

   # clean out the buffer
   $self->{BUFFER} = "";

   # Build the query URL
   my $URL = $self->_build_query();

   # Run the actual HTTP query
   # and get the retrieved buffer
   $self->{BUFFER} = $self->_fetch_url( $URL );

   return;
}

sub _fetch_url {
  my $self = shift;
  my $URL = shift;

  # grab the user agent
  my $ua = $self->useragent;

  # build request
  my $request = new HTTP::Request('GET', $URL);

  # grab page from web
  my $reply = $ua->request($request);

  # Look at the result to see if it worked
  if ( ${$reply}{"_rc"} eq 200 ) {
    # stuff the page contents into the buffer
    return  ${$reply}{"_content"};
  } else {
    croak("Error ${$reply}{_rc}: Failed to establish network connection using url $URL");
  }

}

sub _build_query {
  my $self = shift;

  # grab the base URL
  my $URL = $self->query_url;
  my $options = "";

  # loop round all the options keys and build the query
  my %allow = $self->_get_allowed_options;

  # Translate options
  my %translated = $self->_translate_options();

  foreach my $key ( keys %translated) {
    $options .= "&$key=". $translated{$key}
      if defined $translated{$key};
  }

  # Remove the leading ampersand from the options list because
  # it can cause some forms to fail.
  $options =~ s/^&//;

  # build final query URL
  $URL = $URL . $options;

  return $URL;
}

# L A S T  O R D E R S ------------------------------------------------------

1;