package Astro::Catalog::Transport::WebService;

=head1 NAME

Astro::Catalog::Transport::WebService - A base class for WebService querys


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


This class forms a base class for all the WebService based query classes
in the C<Astro::Catalog> distribution (eg C<Astro::Catalog::Query::Sesame>).


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

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

use SOAP::Lite;
use Net::Domain qw(hostname hostdomain);
use File::Spec;
use Carp;

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

$VERSION = "4.35";

=head1 METHODS

=head2 Constructor

=over 4

=item B<new>

Create a new instance from a hash of options

  $q = new Astro::Catalog::Transport::WebService(
                                            Coords    => new Astro::Coords(),
                                            Radius    => $radius,
                                            Bright    => $magbright,
                                            Faint     => $magfaint,
                                            Sort      => $sort_type,
                                            Number    => $number_out );

returns a reference to an query object. Must only called from
sub-classed constructors.

RA and Dec are also allowed but are deprecated (since with only
RA/Dec the coordinates must always be supplied as J2000 space-separated
sexagesimal format).


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

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

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

  return $block;


=item B<querydb>

Unlike C<Astro::Transport::REST> a default C<querydb()> method is not
provided by this base class, each sub-class must provide its own


sub querydb {
  croak "querydb() must be provided by the subclass\n";

=item B<proxy>

Return (or set) the current proxy for the catalog request.

   $usno->proxy( '' );
   $proxy_url = $usno->proxy();


sub proxy {
   my $self = shift;

   # SOAP::Lite respects the HTTP_proxy environment variable

   if (@_) {
      my $proxy_url = shift;
      $ENV{HTTP_proxy} = $proxy_url;
      $ENV{HTTP_PROXY} = $proxy_url;

   # return the current proxy
   return $ENV{HTTP_proxy};


=item B<urn>

Return the current remote urn for the query

   $host = $q->urn();

Can also be used to set the urn.


sub urn {
  my $self = shift;

  if (@_) {

    # set the url option
    my $urn = shift;
    $self->{URN} = $urn;

  return $self->{URN};


=item B<endpoint>

Return the current endpoint for the query

   $host = $q->endpoint();
   $q->endpoint( '' ););

Can also be used to set the endpoint. If the endpoint is a wsdl file
the SOAP::Lite object will automagically be configured to use the
correct URN, e.g.

   $q->endpoint( '' );


sub endpoint {
  my $self = shift;

  if (@_) {

    # set the url option
    my $endpoint = shift;

    if( $endpoint =~ /wsdl$/ ) {
      $self->{SERVICE} = 1;
    $self->{ENDPOINT} = $endpoint;


  if ( defined $self->{ENDPOINT} ) {
     return $self->{ENDPOINT};
  } else {
     return $self->_default_endpoint();



=head2 General Methods

=over 4

=item B<configure>

Configures the object, takes an options hash as an argument

  $q->configure( %options );

Does nothing if the array is not supplied.


sub configure {
  my $self = shift;
  $self->SUPER::configure( @_ );

# T I M E   A T   T H E   B A R  --------------------------------------------



=head2 Private methods

These methods are for internal use only.

=over 4

=item B<_default_urn>

The default URN for the hostname. Must be specified in a sub-class.

  $host = $q->_default_urn();


sub _default_urn {
  croak "default URN must be specified in subclass\n";

=item B<_default_endpoint>

The default endpoint. Must be specified in a sub-class.

  $host = $q->_default_endpoint();


sub _default_endpoint {
  croak "default endpoint must be specified in subclass\n";

=item B<_is_service>

Whether the webservice uses a URN and $endpoint, or is
a service specified by a WSDL file

  $bool = $q->_is_service();



sub _is_service {
  croak "decision must be made by subclass\n";


Copyright (C) 2001 University of Exeter. All Rights Reserved.
Some modifications copyright (C) 2003 Particle Physics and Astronomy
Research Council. All Rights Reserved.

This program was written as part of the eSTAR project and is free software;
you can redistribute it and/or modify it under the terms of the GNU Public

=head1 AUTHORS

Alasdair Allan E<lt><gt>,
Tim Jenness E<lt>tjenness@cpan.orgE<gt>


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