package XML::Document::RTML;
# ---------------------------------------------------------------------------
#+
# Name:
# XML::Document::RTML
# Purposes:
# Perl module to build and parse RTML documents
# Language:
# Perl module
# Authors:
# Alasdair Allan (aa@astro.ex.ac.uk)
# Revision:
# $Id: RTML.pm,v 1.16 2006/11/17 20:43:26 aa Exp $
# Copyright:
# Copyright (C) 200s University of Exeter. All Rights Reserved.
#-
# ---------------------------------------------------------------------------
=head1 NAME
XML::Document::RTML - module which builds and parses RTML documents
=head1 SYNOPSIS
An object instance can be created from an existing RTML document in a
scalar, or directly from a file on local disk.
my $object = new XML::Document::RTML( XML => $xml );
my $object = new XML::Document::RTML( File => $file );
or via the build method,
my $object = new XML::Document::RTML()
$document = $object->build( %hash );
once instantiated various query methods are supported, e.g.,
my $object = new XML::Document::RTML( File => $file );
my $role = $object->role();
=head1 DESCRIPTION
The module can build and parse RTML documents. Currently only version 2.2
of the standard is supported by the module.
=cut
# L O A D M O D U L E S --------------------------------------------------
use strict;
use vars qw/ $VERSION $SELF /;
use XML::Simple;
use XML::Writer;
use XML::Writer::String;
use Net::Domain qw(hostname hostdomain);
use File::Spec;
use Carp;
use Data::Dumper;
use Scalar::Util qw(reftype);
#use Astro::FITS::Header;
#use Astro::VO::VOTable;
'$Revision: 1.16 $ ' =~ /.*:\s(.*)\s\$/ && ($VERSION = $1);
# C O N S T R U C T O R ----------------------------------------------------
=head1 REVISION
$Id: RTML.pm,v 1.16 2006/11/17 20:43:26 aa Exp $
=head1 METHODS
=head2 Constructor
=over 4
=item B<new>
Create a new instance from a hash of options
my $object = new XML::Document::RTML( %hash );
returns a reference to an message object.
=cut
sub new {
my $proto = shift;
my $class = ref($proto) || $proto;
# bless the query hash into the class
my $block = bless { DOCUMENT => undef, # hash generated by XML::Simple
WRITER => undef, # reference to an XML::Writer
BUFFER => undef, # reference to an XML::Writer::String
DTD => undef
}, $class;
# Configure the object
$block->configure( @_ );
return $block;
}
# B U I L D M E T H O D ------------------------------------------------
sub build {
my $self = shift;
my %args = @_;
# mandatory tags
unless ( exists $args{Type} ) {
return undef;
}
# Loop over the rest of the keys
for my $key (qw / Role Type Version DTD GroupCount ExposureTime Exposure
SignalToNoise Snr Flux ExposureType ExposureUnits
SeriesCount Interval Tolerance Priority TimeConstraint
DeviceType Device FilterType Filter TargetType TargetIdent
Identity TargetName Target CoordinateType Coordtype
RA RAFormat RAUnits Dec DecFormat DecUnits Equinox
Host Port PortNumber ID UniqueID Name ObserverName
RealName User UserName Institution Email EmailAddress
Project Score CompletionTime Time Data / ) {
my $method = lc($key);
$self->$method( $args{$key} ) if exists $args{$key};
}
# open the document
$self->{WRITER}->xmlDecl( 'ISO-8859-1' );
# BEGIN DOCUMENT -------------------------------------------------------
if ( $self->version() == 2.2 ) {
$self->{WRITER}->doctype( 'RTML', '', $self->{DTD} );
} elsif ( $self->version() == 2.1 ) {
$self->{WRITER}->doctype( 'RTML', '',
"http://astro.livjm.ac.uk/HaGS/rtml2.1.dtd" );
} else {
$self->{WRITER}->doctype( 'RTML' );
}
# open the RTML document
# ======================
$self->{WRITER}->startTag( 'RTML','version' => $self->version(),
'type' => $self->type() );
# Contact Tag
# -----------
if( defined $self->user_name() ||
defined $self->real_name() ||
defined $self->institution() ||
defined $self->email() ) {
$self->{WRITER}->startTag( 'Contact', 'PI' => 'true' );
if (defined $self->real_name() ) {
$self->{WRITER}->startTag( 'Name');
$self->{WRITER}->characters( $self->real_name() );
$self->{WRITER}->endTag( 'Name' );
} else {
$self->{WRITER}->emptyTag( 'Name');
}
if (defined $self->user_name() ) {
$self->{WRITER}->startTag( 'User');
$self->{WRITER}->characters( $self->user_name() );
$self->{WRITER}->endTag( 'User' );
} else {
$self->{WRITER}->emptyTag( 'User');
}
if (defined $self->institution() ) {
$self->{WRITER}->startTag( 'Institution');
$self->{WRITER}->characters( $self->institution() );
$self->{WRITER}->endTag( 'Institution' );
} else {
$self->{WRITER}->emptyTag( 'Institution');
}
if (defined $self->email() ) {
$self->{WRITER}->startTag( 'Email');
$self->{WRITER}->characters( $self->email() );
$self->{WRITER}->endTag( 'Email' );
} else {
$self->{WRITER}->emptyTag( 'Email');
}
$self->{WRITER}->endTag( 'Contact' );
} else {
$self->{WRITER}->emptyTag( 'Contact' );
}
# Project Tag
# -----------
if (defined $self->project() ) {
$self->{WRITER}->startTag( 'Project' );
$self->{WRITER}->characters( $self->project() );
$self->{WRITER}->endTag( 'Project' );
} else {
$self->{WRITER}->emptyTag( 'Project' );
}
# Telescope Tag
# -------------
$self->{WRITER}->emptyTag( 'Telescope' );
# IntelligentAgent Tag
# --------------------
if (defined $self->id() && defined $self->host() && defined $self->port() ) {
$self->{WRITER}->startTag( 'IntelligentAgent',
'host' => $self->host(), 'port' => $self->port() );
$self->{WRITER}->characters( $self->id() );
$self->{WRITER}->endTag( 'IntelligentAgent' );
}
# Observation tag
# ---------------
$self->{WRITER}->startTag( 'Observation', 'status' => 'ok' );
# Target
# ------
$self->{WRITER}->startTag( 'Target', ,
'type' => $self->target_type(),
'ident' => $self->target_ident() );
# Target Name
# -----------
if ( defined $self->target() ) {
$self->{WRITER}->startTag( 'TargetName' );
$self->{WRITER}->characters( $self->target() );
$self->{WRITER}->endTag( 'TargetName' );
} else {
$self->{WRITER}->emptyTag( 'TargetName' );
}
# Co-ordinates
# ------------
if ( defined $self->coordinate_type() ) {
$self->{WRITER}->startTag( 'Coordinates',
'type' => $self->coordinate_type());
} else {
$self->{WRITER}->startTag( 'Coordinates' );
}
$self->{WRITER}->startTag( 'RightAscension',
'format' => $self->raformat(),
'units' => $self->raunits() );
$self->{WRITER}->characters( $self->ra() );
$self->{WRITER}->endTag( 'RightAscension' );
$self->{WRITER}->startTag( 'Declination',
'format' => $self->decformat(),
'units' => $self->decunits() );
if ( $self->dec() =~ m/^\+/ ) {
$self->{WRITER}->characters( $self->dec() );
} else {
if ( $self->dec() =~ m/-/ ) {
$self->{WRITER}->characters( $self->dec() );
} else {
$self->{WRITER}->characters( "+" . $self->dec() );
}
}
$self->{WRITER}->endTag( 'Declination' );
$self->{WRITER}->startTag( 'Equinox' );
$self->{WRITER}->characters( $self->equinox() );
$self->{WRITER}->endTag( 'Equinox' );
$self->{WRITER}->endTag( 'Coordinates' );
# Flux
# ----
if( $self->exposure_type() eq "snr" ) {
$self->{WRITER}->startTag( 'Flux',
'type' => 'continuum',
'units' => 'mag',
'wavelength' => $self->filter_type() );
$self->{WRITER}->characters( $self->reference_flux() );
$self->{WRITER}->endTag( 'Flux' );
}
$self->{WRITER}->endTag( 'Target' );
# Device
# ------
$self->{WRITER}->startTag( 'Device', 'type' => $self->device_type() );
# Filter
# ------
$self->{WRITER}->startTag( 'Filter' );
$self->{WRITER}->startTag( 'FilterType');
$self->{WRITER}->characters( $self->filter_type() );
$self->{WRITER}->endTag( 'FilterType' );
$self->{WRITER}->endTag( 'Filter' );
$self->{WRITER}->endTag( 'Device' );
# Schedule
# --------
$self->{WRITER}->startTag( 'Schedule', 'priority' => $self->priority() );
# Exposure
# --------
if ( $self->exposure_type() eq "time" ) {
$self->{WRITER}->startTag( 'Exposure',
'type' => $self->exposure_type(),
'units' => $self->exposure_units() );
if( defined $self->group_count() && $self->group_count() > 1 ) {
$self->{WRITER}->startTag( 'Count');
$self->{WRITER}->characters( $self->group_count() );
$self->{WRITER}->endTag( 'Count' );
}
$self->{WRITER}->characters( $self->exposure_time() );
} else {
$self->exposure_type( "snr" );
$self->{WRITER}->startTag( 'Exposure',
'type' => $self->exposure_type() );
if( defined $self->group_count() && $self->group_count() > 1 ) {
$self->{WRITER}->startTag( 'Count');
$self->{WRITER}->characters( $self->group_count() );
$self->{WRITER}->endTag( 'Count' );
}
$self->{WRITER}->characters( $self->signal_to_noise() );
}
$self->{WRITER}->endTag( 'Exposure' );
# TimeConstraint
# --------------
if( defined $self->start_time() && defined $self->end_time() ) {
$self->{WRITER}->startTag( 'TimeConstraint' );
$self->{WRITER}->startTag( 'StartDateTime' );
$self->{WRITER}->characters( $self->start_time() );
$self->{WRITER}->endTag( 'StartDateTime' );
$self->{WRITER}->startTag( 'EndDateTime' );
$self->{WRITER}->characters( $self->end_time() );
$self->{WRITER}->endTag( 'EndDateTime' );
$self->{WRITER}->endTag( 'TimeConstraint' );
}
# SeriesConstraint
# ----------------
if ( defined $self->series_count() &&
defined $self->interval() &&
defined $self->tolerance() ) {
$self->{WRITER}->startTag( 'SeriesConstraint' );
$self->{WRITER}->startTag( 'Count' );
$self->{WRITER}->characters($self->series_count() );
$self->{WRITER}->endTag( 'Count' );
$self->{WRITER}->startTag( 'Interval' );
$self->{WRITER}->characters( $self->interval() );
$self->{WRITER}->endTag( 'Interval' );
$self->{WRITER}->startTag( 'Tolerance' );
$self->{WRITER}->characters( $self->tolerance() );
$self->{WRITER}->endTag( 'Tolerance' );
$self->{WRITER}->endTag( 'SeriesConstraint' );
}
$self->{WRITER}->endTag( 'Schedule' );
# Data tags
# ---------
my @images = $self->images();
my @image_type = $self->image_type();
my @image_delivery = $self->image_delivery();
my @image_reduced = $self->image_reduced();
my @catalogues = $self->catalogues();
my @catalogue_types = $self->catalogue_type();
my @headers = $self->headers();
my @header_types = $self->header_type();
foreach my $j ( 0 .. $#images ) {
$self->{WRITER}->startTag( 'ImageData',
'type' => $image_type[$j],
'delivery' => $image_delivery[$j],
'reduced' => $image_reduced[$j] );
# FITSHeader
# ----------
if( defined $headers[$j] && defined $header_types[$j] ) {
$self->{WRITER}->startTag( 'FITSHeader', 'type' => $header_types[$j] );
$self->{WRITER}->characters( $headers[$j] );
$self->{WRITER}->endTag( 'FITSHeader' );
}
# ObjectList
# ----------
if ( defined $catalogues[$j] && defined $catalogue_types[$j] ) {
$self->{WRITER}->startTag( 'ObjectList', 'type' => $catalogue_types[$j] );
$self->{WRITER}->characters( $catalogues[$j] );
$self->{WRITER}->endTag( 'ObjectList' );
}
# FITS file
# ---------
$self->{WRITER}->characters( $images[$j] );
$self->{WRITER}->endTag( 'ImageData' );
}
$self->{WRITER}->endTag( 'Observation' );
# Score Tags
# ----------
if (defined $self->{DOCUMENT}->{Score} ) {
$self->{WRITER}->startTag( 'Score' );
$self->{WRITER}->characters( $self->{DOCUMENT}->{Score} );
$self->{WRITER}->endTag( 'Score' );
}
if ( defined $self->{DOCUMENT}->{CompletionTime} ) {
$self->{WRITER}->startTag( 'CompletionTime' );
$self->{WRITER}->characters( $self->{DOCUMENT}->{CompletionTime} );
$self->{WRITER}->endTag( 'CompletionTime' );
}
# close the RTML DOCUMENT
# =======================
$self->{WRITER}->endTag( 'RTML' );
$self->{WRITER}->end();
# END DOCUMENT --------------------------------------------------------
my $xml = $self->{BUFFER}->value();
$self->_parse( XML => $xml ); # populates the object with a parsed document
return $xml;
}
# A C C E S S O R M E T H O D S -------------------------------------------
=back
=head2 Accessor Methods
=over 4
=item B<type>
Return, or set, the type of the RTML document
my $type = $object->type();
$object->type( $type );
=cut
sub role {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{type} = shift;
}
return $self->{DOCUMENT}->{type};
}
sub type {
role( @_ );
}
sub determine_type {
role( @_ );
}
=item B<version>
Return, or set, the version of the RTML specification used
my $version = $object->version();
$object->version( $version );
=cut
sub version {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{version} = shift;
}
return $self->{DOCUMENT}->{version};
}
sub dtd {
version( @_ );
}
# S C H E D U L E #########################################################
=back
=head2 Scheduling Methods
=over 4
=item B<group_count>
Return, or set, the group count of the observation
my $num = $object->group_count();
$object->group_count( $num );
=cut
sub group_count {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{Count} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{Count};
}
sub groupcount {
group_count( @_ );
}
=item B<exposure_time>
Return, or set, the exposure time of the observation
my $num = $object->exposure_time();
$object->exposure_time( $num );
=cut
sub exposure_time {
my $self = shift;
if (@_) {
my $exposure = shift;
if ( defined $self->exposure_units() && $self->exposure_units() eq "ms" ) {
$exposure = $exposure / 1000.0;
}
$exposure =~ s/^\s*//;
$exposure =~ s/\s*$//;
$self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{content} = $exposure;
$self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{type} = "time";
$self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{units} = "seconds";
}
my $exposure = $self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{content};
if ( defined $exposure ) {
$exposure =~ s/^\s*//;
$exposure =~ s/\s*$//;
if ( $self->exposure_units() eq "ms" ) {
$exposure = $exposure / 1000.0;
$self->exposure_units( "seconds" );
}
}
return $exposure;
}
sub exposuretime {
exposure_time( @_ );
}
sub exposure {
exposure_time( @_ );
}
=item B<signal_to_noise>
Return, or set, the S/N of the observation
my $num = $object->signal_to_noise();
$object->signal_to_noise( $num );
=cut
sub signal_to_noise {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{content} = shift;
$self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{type} = "snr";
}
return $self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{content};
}
sub signaltonoise {
signal_to_noise( @_ );
}
sub snr {
signal_to_noise( @_ );
}
=item B<reference_flux>
Sets (or returns) the flux of the object needed for signal to noise
calculations for the image
my $mag = $object->reference_flux();
$object->reference_flux( $mag );
the flux should be a continuum R band magnitude value.
=cut
sub reference_flux {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{Flux}->{content} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{Flux}->{content};
}
sub flux {
reference_flux( @_ );
}
=item B<exposure_type>
Return, or set, the type of exposure of the observation
my $string = $object->exposure_type();
$object->exposure_type( $string );
where $string can have values of "snr" or "time".
=cut
sub exposure_type {
my $self = shift;
if (@_) {
my $type = shift;
if ( $type eq "snr" ) {
$self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{type} = "snr";
} else {
$self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{type} = "time";
$self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{units} = "seconds";
}
}
return $self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{type};
}
sub exposuretype {
exposure_type( @_ );
}
sub exposure_units {
my $self = shift;
return $self->{DOCUMENT}->{Observation}->{Schedule}->{Exposure}->{units};
}
sub exposureunits {
exposure_units( @_ );
}
=item B<series_count>
Return, or set, the series count of the observation
my $num = $object->series_count();
$object->series_count( $num );
=cut
sub series_count {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Schedule}->{SeriesConstraint}->{Count} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Schedule}->{SeriesConstraint}->{Count};
}
sub seriescount {
series_count( @_ );
}
=item B<interval>
Return, or set, the interval between a series of observations blocks
my $num = $object->interval();
$object->interval( $num );
=cut
sub interval {
my $self = shift;
if (@_) {
my $arg = shift;
unless ( $arg =~ "PT" ) {
$arg = "PT" . $arg;
}
$self->{DOCUMENT}->{Observation}->{Schedule}->{SeriesConstraint}->{Interval} = $arg;
}
return $self->{DOCUMENT}->{Observation}->{Schedule}->{SeriesConstraint}->{Interval};
}
=item B<tolerance>
Return, or set, the tolerance between a series of observations blocks
my $num = $object->tolerance();
$object->tolerance( $num );
=cut
sub tolerance {
my $self = shift;
if (@_) {
my $arg = shift;
unless ( $arg =~ "PT" ) {
$arg = "PT" . $arg;
}
$self->{DOCUMENT}->{Observation}->{Schedule}->{SeriesConstraint}->{Tolerance} = $arg;
}
return $self->{DOCUMENT}->{Observation}->{Schedule}->{SeriesConstraint}->{Tolerance};
}
=item B<priority>
Return, or set, the priority of the observation
my $num = $object->priority();
$object->priority( $num );
Schedule (RTML) priority Phase II Priority Phase II GUI
N/A 5 Urgent
0 4 (default) Normal
1 3 High
2 2 Medium
3 1 Normal
default(other) 1 Normal
N/A 0 Normal
where: "Schedule (RTML) priority" is the number specified in the RTML:
<Schedule priority="n">, "Phase II Priority" is the number stored in the
Phase II database and "Phase II GUI" is what is displayed in the Phase II GUI.
Note:
The Phase II priority 4 can be specified by the TEA but cannot be specified
by the Phase II GUI (and displays as the default "Normal" in the GUI). The
Phase II priority 5 I<cannot> be specified by the TEA but can be specified by
the Phase II GUI as Urgent.
=cut
sub priority {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Schedule}->{priority} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Schedule}->{priority};
}
sub schedule_priority {
priority( @_ );
}
=item B<time_constraint>
Return, or set, the time constraints of the the observation
my $array_reference = $object->time_constraint();
$object->exposure_type( \@times );
where it takes and returns a scalar reference to an array of ISO8601
times, e.g. my $array_reference = [ $start, $end ] which maps to,
<TimeConstraint>
<StartDateTime>2006-09-10T11:12:51+0100</StartDateTime>
<EndDateTime>2006-09-12T00:12:51+0100</EndDateTime>
</TimeConstraint>
=cut
sub time_constraint {
my $self = shift;
if (@_) {
my $ref = shift;
my @array = @{$ref};
$self->{DOCUMENT}->{Observation}->{Schedule}->{TimeConstraint}->{StartDateTime} = $array[0];
$self->{DOCUMENT}->{Observation}->{Schedule}->{TimeConstraint}->{EndDateTime} = $array[1];
}
return ( $self->{DOCUMENT}->{Observation}->{Schedule}->{TimeConstraint}->{StartDateTime},
$self->{DOCUMENT}->{Observation}->{Schedule}->{TimeConstraint}->{EndDateTime} );
}
sub timeconstraint {
time_constraint( @_ );
}
sub start_time {
my $self = shift;
return $self->{DOCUMENT}->{Observation}->{Schedule}->{TimeConstraint}->{StartDateTime};
}
sub end_time{
my $self = shift;
return $self->{DOCUMENT}->{Observation}->{Schedule}->{TimeConstraint}->{EndDateTime};
}
# D E V I C E ##############################################################
=back
=head2 Device Methods
=over 4
=item B<device_type>
Return, or set, the device type for the observation
my $string = $object->device_type();
$object->device_type( $string );
=cut
sub device_type {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Device}->{type} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Device}->{type};
}
sub devicetype {
device_type( @_ );
}
sub device {
device_type( @_ );
}
=item B<filter_type>
Return, or set, the filter type for the observation
my $string = $object->filter_type();
$object->filter_type( $string );
=cut
sub filter_type {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Device}->{Filter}->{FilterType} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Device}->{Filter}->{FilterType};
}
sub filtertype {
filter_type( @_ );
}
sub filter {
filter_type( @_ );
}
# T A R G E T ##############################################################
=back
=head2 Target Methods
=over 4
=item B<target_type>
Return, or set, the type of target for the observation
my $string = $object->target_type();
$object->target_type( $string );
there are two types of valid target type; "normal" or "toop". A normal
observation is placed into the queue
=cut
sub target_type {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{type} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{type};
}
sub targettype {
target_type( @_ );
}
=item B<target_ident>
Return, or set, the type identifier of target for the observation
my $string = $object->target_ident();
$object->target_ident( $string );
The target identity is used by the eSTAR system to choose post-observation
processing blocks, e.g.
<Target type="normal" ident="ExoPlanetMonitor">
signifies a normal queued observation which is part of the exo-planet
monitoring programme on Robonet-1.0.
=cut
sub target_ident {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{ident} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{ident};
}
sub targetident {
target_ident( @_ );
}
sub identity {
target_ident( @_ );
}
=item B<target_name>
Return, or set, the target name for the observation
my $string = $object->target_name();
$object->target_name( $string );
=cut
sub target_name {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{TargetName} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{TargetName};
}
sub targetname {
target_name( @_ );
}
sub target {
target_name( @_ );
}
=item B<coordinate_type>
Sets (or returns) the type of co-ordinate system expected,
my $ra = $object->coordinate_type();
$object->coordinate_type( 'equatorial' );
defaults to "equatorial". Don't change this unless you know what you're
doing and set all the other relevant parameters via the relevant private
methods provided by the class.
=cut
sub coordinate_type {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{type} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{type};
}
sub coord_type {
coordinate_type( @_ );
}
sub coordinatetype {
coordinate_type( @_ );
}
sub coordtype {
coordinate_type( @_ );
}
=item B<ra>
Sets (or returns) the target RA
my $ra = $object->ra();
$object->ra( '12 35 65.0' );
must be in the form HH MM SS.S.
=cut
sub ra {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{RightAscension}->{content} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{RightAscension}->{content};
}
sub ra_format {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{RightAscension}->{format} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{RightAscension}->{format};
}
sub raformat {
ra_format( @_ );
}
sub ra_units {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{RightAscension}->{units} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{RightAscension}->{units};
}
sub raunits {
ra_units( @_ );
}
=item B<dec>
Sets (or returns) the target DEC
my $dec = $object->dec();
$object->dec( '+60 35 32' );
must be in the form SDD MM SS.S.
=cut
sub dec {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{Declination}->{content} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{Declination}->{content};
}
sub dec_format {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{Declination}->{format} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{Declination}->{format};
}
sub decformat {
dec_format( @_ );
}
sub dec_units {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{Declination}->{units} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{Declination}->{units};
}
sub decunits {
dec_units( @_ );
}
=item B<equinox>
Sets (or returns) the equinox of the target co-ordinates
my $equnox = $object->equinox();
$object->equinox( 'B1950' );
default is J2000, currently the telescope expects J2000.0 coordinates, no
translation is currently carried out by the library before formatting the
RTML message. It is therefore suggested that the user provides their
coordinates in J2000.0 as this is merely a placeholder routine.
=cut
sub equinox {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{Equinox} = shift;
}
return $self->{DOCUMENT}->{Observation}->{Target}->{Coordinates}->{Equinox};
}
# A G E N T ##############################################################
=back
=head2 Agent Methods
=over 4
=item B<host>
Return, or set, the host to return asynchronous messages to regarding the
status of the observation, see also C<port( )>.
my $string = $object->host();
$object->host( $string );
defaults to the current machine's IP address
=cut
sub host {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{IntelligentAgent}->{host} = shift;
}
return $self->{DOCUMENT}->{IntelligentAgent}->{host};
}
sub host_name {
host( @_ );
}
sub agent_host {
host( @_ );
}
=item B<port>
Return, or set, the port to return asynchronous messages to regarding the
status of the observation, see also C<host( )>.
my $string = $object->port();
$object->port( $string );
defaults to 8000.
=cut
sub port {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{IntelligentAgent}->{port} = shift;
}
return $self->{DOCUMENT}->{IntelligentAgent}->{port};
}
sub port_number {
port( @_ );
}
sub portnumber {
port( @_ );
}
=item B<id>
Sets (or returns) the unique ID for the observation request
my $id = $object->id();
$object->id( 'IATEST0001:CT1:0013' );
note that there is NO DEFAULT, a unique ID for the score/observing
request must be supplied, see the eSTAR Communications and the TEA
command set documents for further details.
Note: This is I<not> the same thing as the I<target identity> for the
observation.
=cut
sub id {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{IntelligentAgent}->{content} = shift;
}
# return the current ID
return $self->{DOCUMENT}->{IntelligentAgent}->{content};
}
sub unique_id {
id( @_ );
}
sub uniqueid {
id( @_ );
}
# C O N A C T ##############################################################
=back
=head2 Contact Methods
=over 4
=item B<name>
Return, or set, the name of the observer
my $string = $object->name();
$object->name( $string );
=cut
sub name {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Contact}->{Name} = shift;
}
return $self->{DOCUMENT}->{Contact}->{Name};
}
sub observer_name {
name( @_ );
}
sub real_name {
name( @_ );
}
sub observername {
name( @_ );
}
sub realname {
name( @_ );
}
=item B<user>
Return, or set, the user name of the observer
my $string = $object->user();
$object->user( $string );
e.g. PATT/keith.horne
=cut
sub user {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Contact}->{User} = shift;
}
return $self->{DOCUMENT}->{Contact}->{User};
}
sub user_name {
user( @_ );
}
sub username {
user( @_ );
}
=item B<institution>
Return, or set, the institutional affliation of the observer
my $string = $object->institution();
$object->institution( $string );
e.g. University of Exeter
=cut
sub institution {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Contact}->{Institution} = shift;
}
return $self->{DOCUMENT}->{Contact}->{Institution};
}
sub institution_affiliation {
institution( @_ );
}
=item B<email>
Return, or set, the email address of the observer
my $string = $object->email();
$object->email( $string );
=cut
sub email {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Contact}->{Email} = shift;
}
return $self->{DOCUMENT}->{Contact}->{Email};
}
sub email_address {
email( @_ );
}
sub emailddress {
email( @_ );
}
=item B<project>
Return, or set, the user name of the observer
my $string = $object->user();
$object->user( $string );
e.g. PATT/keith.horne
=cut
sub project {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Project} = shift;
}
my $project = $self->{DOCUMENT}->{Project};
return $project unless defined reftype($project);
$project = undef if reftype($project) eq "HASH"; # hash implies an empty tag
return $project;
}
# S C O R I N G ##############################################################
=back
=head2 Scoring Methods
=over 4
=item B<score>
Sets (or returns) the target score
my $score = $object->score();
$object->score( $score );
the score will be between 0.0 and 1.0
=cut
sub score {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{Score} = shift;
}
# return the current target score
return $self->{DOCUMENT}->{Score};
}
=item B<completion_time>
Sets (or returns) the target completion time
my $time = $object->completion_time();
$object->completion_time( $time );
the completion time should be of the format YYYY-MM-DDTHH:MM:SS
=cut
sub completion_time {
my $self = shift;
if (@_) {
$self->{DOCUMENT}->{CompletionTime} = shift;
}
# return the current target score
return $self->{DOCUMENT}->{CompletionTime};
}
sub completiontime {
completion_time( @_ );
}
sub time {
completion_time( @_ );
}
# D A T A ################################################################
=back
=head2 Data Methods
=over 4
=item B<data>
Sets (or returns) the data associated with the observation
my @data = $object->data( );
$object->data( @data );
Takes an array of hashes where,
@data = [ { Catalogue => ' ', Header => ' ', URL => ' ' },
{ Catalogue => ' ', Header => ' ', URL => ' ' },
.
.
.
{ Catalogue => ' ', Header => ' ', URL => ' ' } ];
and the value of the Catalogue hash entry is a URL pointing to a VOTavle,
the Header hash entry is a FITS header block and the URL is either points
to a FITS file, or other associated data product. You can I<not> append
data to an existing memory structure, any data passed via this routine
will overwrite any existing data structure in memory.
The routine returns a similar array when queried. This array will be
populated either by calling C<build( )>, or through parsing a document.
=cut
sub data {
my $self = shift;
# TAKING DATA INTO THE MESSAGE
if (@_) {
my @array = @_;
$self->{DOCUMENT}->{Observation}->{ImageData} = [];
foreach my $i ( 0 ... $#array ) {
my %hash = %{$array[$i]};
# Images
if ( defined $hash{URL} ) {
$self->{DOCUMENT}->{Observation}->{ImageData}[$i]->{content} = $hash{URL};
$self->{DOCUMENT}->{Observation}->{ImageData}[$i]->{delivery} = "url";
$self->{DOCUMENT}->{Observation}->{ImageData}[$i]->{type} = "FITS16";
$self->{DOCUMENT}->{Observation}->{ImageData}[$i]->{reduced} = "true";
}
# Catalogues
if( defined $hash{Catalogue} ) {
$self->{DOCUMENT}->{Observation}->{ImageData}[$i]->{ObjectList}->{content} = $hash{Catalogue};
if( $hash{Catalogue} =~ "http" && $hash{Catalogue} =~ "votable" ) {
$self->{DOCUMENT}->{Observation}->{ImageData}[$i]->{ObjectList}->{type} = "votable-url";
} else {
$self->{DOCUMENT}->{Observation}->{ImageData}[$i]->{ObjectList}->{type} = "unknown";
}
}
# FITS Headers
if( defined $hash{Catalogue} ) {
$self->{DOCUMENT}->{Observation}->{ImageData}[$i]->{FITSHeader}->{content} = $hash{Header};
$self->{DOCUMENT}->{Observation}->{ImageData}[$i]->{FITSHeader}->{type} = "all";
}
} # end of foreach loop
} # end of if ( @_ ) block
# PUSHING DATA OUT OF THE MESSAGE
if ( defined $self->{DOCUMENT}->{Observation}->{ImageData} &&
reftype($self->{DOCUMENT}->{Observation}->{ImageData}) eq "HASH" ) {
return ();
}
my @output;
foreach my $j ( 0 .. $#{$self->{DOCUMENT}->{Observation}->{ImageData}} ) {
my $header = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{FITSHeader}->{content};
my $url = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{content};
my $catalogue = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{ObjectList}->{content};
if ( defined $url ) {
$url =~ s/^\s*//;
$url =~ s/\s*$//;
}
if ( defined $catalogue ) {
$catalogue =~ s/^\s*//;
$catalogue =~ s/\s*$//;
}
$output[$j] = ( { Catalogue => $catalogue,
URL => $url,
Header => $header } );
}
return @output;
}
sub headers {
my $self = shift;
if ( defined $self->{DOCUMENT}->{Observation}->{ImageData} &&
reftype($self->{DOCUMENT}->{Observation}->{ImageData}) eq "HASH" ) {
return ();
}
my @output;
foreach my $j ( 0 .. $#{$self->{DOCUMENT}->{Observation}->{ImageData}} ) {
my $header = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{FITSHeader}->{content};
$output[$j] = $header;
}
return @output;
}
sub images {
my $self = shift;
if ( defined $self->{DOCUMENT}->{Observation}->{ImageData} &&
reftype($self->{DOCUMENT}->{Observation}->{ImageData}) eq "HASH" ) {
return ();
}
my @output;
foreach my $j ( 0 .. $#{$self->{DOCUMENT}->{Observation}->{ImageData}} ) {
my $url = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{content};
if ( defined $url ) {
$url =~ s/^\s*//;
$url =~ s/\s*$//;
}
$output[$j] = $url;
}
return @output;
}
sub catalogues {
my $self = shift;
if ( defined $self->{DOCUMENT}->{Observation}->{ImageData} &&
reftype($self->{DOCUMENT}->{Observation}->{ImageData}) eq "HASH" ) {
return ();
}
my @output;
foreach my $j ( 0 .. $#{$self->{DOCUMENT}->{Observation}->{ImageData}} ) {
my $catalogue = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{ObjectList}->{content};
if ( defined $catalogue ) {
$catalogue =~ s/^\s*//;
$catalogue =~ s/\s*$//;
}
$output[$j] = $catalogue;
}
return @output;
}
sub image_delivery {
my $self = shift;
my @output;
foreach my $j ( 0 .. $#{$self->{DOCUMENT}->{Observation}->{ImageData}} ) {
my $delivery = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{delivery};
$output[$j] = $delivery;
}
return @output;
}
sub image_type {
my $self = shift;
my @output;
foreach my $j ( 0 .. $#{$self->{DOCUMENT}->{Observation}->{ImageData}} ) {
my $type = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{type};
$output[$j] = $type;
}
return @output;
}
sub image_reduced {
my $self = shift;
my @output;
foreach my $j ( 0 .. $#{$self->{DOCUMENT}->{Observation}->{ImageData}} ) {
my $reduced = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{reduced};
$output[$j] = $reduced;
}
return @output;
}
sub catalogue_type {
my $self = shift;
my @output;
foreach my $j ( 0 .. $#{$self->{DOCUMENT}->{Observation}->{ImageData}} ) {
my $type = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{ObjectList}->{type};
$output[$j] = $type;
}
return @output;
}
sub header_type {
my $self = shift;
my @output;
foreach my $j ( 0 .. $#{$self->{DOCUMENT}->{Observation}->{ImageData}} ) {
my $type = $self->{DOCUMENT}->{Observation}->{ImageData}[$j]->{FITSHeader}->{type};
$output[$j] = $type;
}
return @output;
}
# G E N E R A L ------------------------------------------------------------
=back
=head2 General Methods
=over 4
=item B<dump_buffer>
Dumps the contents of the RTML buffer in memory to a scalar,
my $object = new XML::Document::RTML();
$object->build( %hash );
my $document = $object->dump_buffer();
If C<build( )> has not been called this function will return an undef.
=cut
sub dump_buffer {
my $self = shift;
if ( defined $self->{BUFFER} ){
return $self->{BUFFER}->value();
} else {
return undef;
}
}
sub dump_rtml {
dump_buffer( @_ );
}
sub buffer {
dump_buffer( @_ );
}
=item B<dump_tree>
Returns a refence to the parsed RTML document hash currently held in memory,
my $object = new XML::Document::RTML( XML => $xml );
my $hash_reference = $object->dump_tree();
should return an undefined value if that tree is empty. This error will occur
if we haven't called C<build( )> to create a document, or populated the tree using
the object creator by calling the XML or File methods to read in a document.
=cut
sub dump_tree {
my $self = shift;
if ( defined $self->{DOCUMENT} ){
return $self->{DOCUMENT};
} else {
return undef;
}
}
sub dump_hash {
dump_tree( @_ );
}
sub tree {
dump_tree( @_ );
}
# C O N F I G U R E ---------------------------------------------------------
=item B<configure>
Configures the object, takes an options hash as an argument
$message->configure( %options );
Does nothing if the hash is not supplied. This is called directly from
the constructor during object creation
=cut
sub configure {
my $self = shift;
# BLESS XML WRITER
# ----------------
$self->{BUFFER} = new XML::Writer::String();
$self->{WRITER} = new XML::Writer( OUTPUT => $self->{BUFFER},
DATA_MODE => 1,
UNSAFE => 1,
DATA_INDENT => 4 );
# DEFAULTS
# --------
# use the RTML Namespace as defined by the v2.2 DTD by default
$self->version( 2.2 );
$self->{DTD} = "http://www.estar.org.uk/documents/rtml" . $self->version() . ".dtd";
# we're guessing we're talking to
$self->host( "127.0.0.1" );
$self->port( 8000 );
# default to J2000
$self->coordinate_type( "equatorial" );
$self->equinox ( "J2000" );
$self->raformat( "hh mm ss.ss" );
$self->raunits( "hms" );
$self->decformat( "dd mm ss.ss" );
$self->decunits( "dms" );
# default to using the queue with "normal" priority
$self->priority( 3 );
$self->target_type( "normal" );
$self->target_ident( "SingleExposure" );
$self->exposure_type( "time" );
# default to a CCD camera, and an R-band filter
$self->device_type( "camera" );
$self->filter_type( "R" );
# CONFIGURE FROM ARGUEMENTS
# -------------------------
# return unless we have arguments
return undef unless @_;
# grab the argument list
my %args = @_;
# Loop over the keys that mean we're parsing a document
for my $key (qw / File XML / ) {
if ( lc($key) eq "file" && exists $args{$key} ) {
eval { $self->_parse( File => $args{$key} ); };
if ( $@ ) {
die "$@";
}
last;
} elsif ( lc($key) eq "xml" && exists $args{$key} ) {
eval { $self->_parse( XML => $args{$key} ); };
if ( $@ ) {
die "$@";
}
last;
}
}
# Loop over the rest of the keys
for my $other (qw / Role Type Version DTD GroupCount ExposureTime Exposure
SignalToNoise Snr Flux ExposureType ExposureUnits
SeriesCount Interval Tolerance Priority TimeConstraint
DeviceType Device FilterType Filter TargetType TargetIdent
Identity TargetName Target CoordinateType Coordtype
RA RAFormat RAUnits Dec DecFormat DecUnits Equinox
Host Port PortNumber ID UniqueID Name ObserverName
RealName User UserName Institution Email EmailAddress
Project Score CompletionTime Time Data / ) {
my $method = lc($other);
$self->$method( $args{$other} ) if exists $args{$other};
}
# Nothing to configure...
return undef;
}
# P R I V A T E M E T H O D S ------------------------------------------
sub _parse {
my $self = shift;
# return unless we have arguments
return undef unless @_;
# grab the argument list
my %args = @_;
my $xs = new XML::Simple( );
# Loop over the allowed keys
for my $key (qw / File XML / ) {
if ( lc($key) eq "file" && exists $args{$key} ) {
$args{$key} =~ s/US_ASCII/ISO-8859-1/;
$self->{DOCUMENT} = $xs->XMLin( $args{$key}, ForceArray => [ "ImageData" ] );
last;
} elsif ( lc($key) eq "xml" && exists $args{$key} ) {
$args{$key} =~ s/US_ASCII/ISO-8859-1/;
$self->{DOCUMENT} = $xs->XMLin( $args{$key}, ForceArray => [ "ImageData" ] );
last;
}
}
#print Dumper( $self->{DOCUMENT} );
return;
}
# L A S T O R D E R S ------------------------------------------------------
1;