/ 
Astro-NED-Query-0.31
River stage zero No dependents
/ Astro::NED::Query

NAME

Astro::NED::Query - base class for NED queries

SYNOPSIS

use base qw/ Astro::NED::Query /;

DESCRIPTION

This class is the base class for queries to NED. As such, it is not used directly in end-user applications. Use the classes Astro::NED::Query::ByName, Astro::NED::Query::NearName, Astro::NED::Query::NearPosition instead.

However, since most of the functionality of those classes is derived from this one, most of the documentation for their use is found here. Documentation for the other classes will provide class specific details.

USAGE

Constructing a query

Queries are constructed by creating a query object. The object should be created in one of the classes listed above. _You cannot construct a pure Astro::NED::Query object.

For example, the construct a by name query,

$query = Astro::NED::Query::ByName->new( Field1 => $value1,
                                         Field2 => $value2, ... );

This constructs a query, setting the query parameters Field1 and Field2. It does not send off the query. Only single valued parameters may be set when constructing the query.

When an object is constructed, the appropriate search parameter form is retrieved from NED. To avoid repeatedly doing this, reuse a query object as much as possible.

Query Parameters and Accessor Methods

Query parameters come in two flavors: single valued and multiple valued. As shown above, single valued query parameters may be specified in the constructor.

Once a query has been constructed, parameters may be set or retrieved using accessor methods. These methods have the same name as the parameter. For single valued fields,

$query->Field1( $value );
$value = $query->Field1;

Accessor methods for fields which can have multiple concurrent values have a slightly different syntax:

$query->MField( $value => $state );
$state = $query->MField( $value );

Here, $state is a boolean value which indicates whether or not the field should contain that value. Think of it as a check box toggle switch. The value returned by the accessor will be empty if the field contains that value, else it is the actual value.

All of the parameters may be set to their default state by calling the set_to_defaults method. To make the default values look like the current values, use the save_as_defaults method.

Some parameters may have values which are restricted to a given set. To determine what the available values are, use the possible_values method.

Sending off the request

Once a query has been constructed, it is sent off to NED with the query method. This method will return an object (in the computer science sense) which contains the results of the query. The type of object returned depends upon the type of query. For instance, queries which fall under the NED "Objects" rubric all return an Astro::NED::Response::Objects object.

The query object may be reused as often as one would like; simply change the parameter values and reissue the query method.

Examples

Querying by name
$req = Astro::NED::Query::ByName->new( ObjName => 'Abell 2166',
                                       Extend => 1 );
$res = $req->query;
print $_->Name, "\n" foreach $res->objects;
Querying near name for Galaxies with X-ray emission
$req = Astro::NED::Query::NearName->new( ObjName => 'Abell 2166');
$req->IncObjType( Galaxies => 1 );
$req->IncObjType( Xray => 1 );
$req->ObjTypeInclude( 'ALL' );
$res = $req->query;
print $_->Name, "\n" foreach $res->objects;

GENERIC OBJECT METHODS

All of the various Query classes share the following methods. Make sure to read the documentation for the actual Query class which will be used. It contains class specific information.

new

This is the object constructor. It takes a list of keyword and value pairs. The keywords may be the names of single valued query parameters. These are documented for each Query class.

dump

Returns the current parameters as a textual representation. See HTML::Form::dump() for more information.

form
@keyw = $req->form;

Returns the current parameters as a sequence of key/value pairs. See HTML::Form::form() for more information.

get
$req->get( $field_name );

Generic method to get a field value. Cannot be used for multiple value fields.

getMultiple
$state = $req->getMultiple( $field_name, $value);

Generic method to get a multiple value field's state.

possible_values
@values = $req->possible_values( $field_name );

This returns a list of the possible values for a query parameter. This is only useful for parameters whose values are limited to a specific set of values. For other parameters, an empty list is returned.

set_to_defaults
$req->set_to_defaults;

This method sets the parameter values to their defaults. The default values are initially taken from the NED defaults, but may be changed with the save_as_defaults method.

set
$req->set( $field_name, $value );

Generic method to set a field's value. Cannot be used for multiple value fields.

setMultiple
$req->setMultiple( $field_name, $value);
$req->setMultiple( $field_name, $value, $state );

Generic method to set a multiple value field's state. If $state is not present or is zero then the value is removed from the field, otherwise the value is set.

save_as_defaults
$req->save_as_defaults;

This saves the current parameter values as the default values.

query
$res = $req->query;

Send the query off to NED. It returns a container containing the results of the query. See the documentation for the separate Query classes for information on the type of container and how to extract data from it.

timeout
$req->timeout();
$req->timeout( $seconds );

Get/set the timeout value in seconds. See LWP::UserAgent::timeout() for more information.

EXPORT

None by default.

AUTHOR

Diab Jerius, <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (C) 2003 Smithsonian Astrophysical Observatory. All rights are of course reserved.

It is released under the GNU General Public License. You may find a copy at

http://www.fsf.org/copyleft/gpl.html

SEE ALSO

Astro::NED::Query::Objects, Astro::NED::Query::ByName, Astro::NED::Query::NearName, Astro::NED::Query::NearPosition, Astro::NED::Query::Response::Objects, Astro::NED::Query::Response::Object, perl.