lib/MOBY/Client/ServiceInstance.pm

   1 package MOBY::Client::ServiceInstance;
   2 use strict;
   3 use Carp;
   4 use vars qw($AUTOLOAD @ISA);
   5
   6 =head1 NAME
   7
   8 MOBY::Client::ServiceInstance - a small object describing a MOBY service
   9
  10 =head1 SYNOPSIS
  11
  12  use MOBY::Client::ServiceInstance;
  13  my $Instance = MOBY::Client::ServiceInstance->new(
  14      authority => 'bioinfo.pbi.nrc.ca',
  15      authoritative => 0,
  16      URL => http://bioinfo.pbi.nrc.ca/runMe.pl,
  17      contactEmail => markw@illumin.com,
  18      name => 'marksFabulousService',
  19      type => 'Retrieve',
  20      input => [$SimpleArticle],
  21      category => 'moby',
  22      output => [$CollectionArticle, $SecondaryArticle],
  23      description => 'retrieves random sequences from a database',
  24          XML => $xml, # the XML from MOBY::Central::findService
  25          );
  26
  27 =cut
  28
  29 =head1 DESCRIPTION
  30
  31 a simple get/set object to hold information about a service instance.
  32
  33 This object is created by MOBY::Client::Central, and is not particularly
  34 useful for anyone else to create it... it is meant to be read-only
  35
  36 =head1 AUTHORS
  37
  38 Mark Wilkinson (markw at illuminae dot com)
  39
  40 BioMOBY Project:  http://www.biomoby.org
  41
  42
  43 =cut
  44
  45 =head1 METHODS
  46
  47
  48 =head2 new
  49
  50  Title     :    new
  51  Usage     :    my $MOBY = MOBY::Client::ServiceInstance->new(%args)
  52  Function  :    create ServiceInstance object
  53  Returns   :    MOBY::Client::ServiceInstance object
  54  Args      :    authority : required : string : default NULL
  55                             teh URI of the service provider
  56                 name      : required : string : default NULL
  57                             the name of the service
  58                 type      : required : string : default NULL
  59                             the type of service from ontology
  60                 input    : required : listref : default empty listref
  61                             the SimpleArticle and CollectionArticle inputs for the service
  62                 output    : required : listref : default empty listref
  63                             the SimpleArticle and CollectionArticle outputs for the service
  64                 description : required : string : default NULL
  65                             human-readable description of service
  66
  67 =cut
  68
  69 =head2 authority
  70
  71  Title     :    authority
  72  Usage     :    $URI = $Service->authority($arg)
  73  Args      :    (optional) scalar string with authority URI
  74  Function  :    get/set authority
  75  Returns   :    string
  76
  77 =cut
  78
  79 =head2 name
  80
  81  Title     :    name
  82  Usage     :    $name = $Service->name($arg)
  83  Args      :    (optional) scalar string with service name
  84  Function  :    get/set name
  85  Returns   :    string
  86
  87 =cut
  88
  89 =head2 type
  90
  91  Title     :    type
  92  Usage     :    $type = $Service->type($arg)
  93  Args      :    (optional) scalar string with servivce type ontology term
  94  Function  :    get/set type
  95  Returns   :    string
  96
  97 =cut
  98
  99 =head2 input
 100
 101  Title     :    input
 102  Usage     :    $input = $Service->input($args)
 103  Args      :    (optional) listref of SimpleArticle,
 104                 CollectionArticle, or SecondaryArticle objects
 105  Function  :    get/set input
 106  Returns   :    listref of MOBY::Client::SimpleArticle
 107                 and/or MOBY::Client::CollectionArticle objects
 108
 109 =cut
 110
 111 =head2 output
 112
 113  Title     :    output
 114  Usage     :    $output = $Service->output($args)
 115  Args      :    (optional) listref of SimpleArticle,
 116                 CollectionArticle, or SecondaryArticle objects
 117  Function  :    get/set output
 118  Returns   :    listref of MOBY::Client::SimpleArticle
 119                 and/or MOBY::Client::CollectionArticle objects
 120
 121 =cut
 122
 123 =head2 description
 124
 125  Title     :    description
 126  Usage     :    $description = $Service->description($arg)
 127  Args      :    (optional) scalar string with description
 128  Function  :    get/set description
 129  Returns   :    string
 130
 131 =cut
 132
 133 =head2 authoritative
 134
 135  Title     :    authoritative
 136  Usage     :    $auth = $Service->authoritative(1|0)
 137  Args      :    (optional) boolean 1 or 0
 138  Function  :    get/set authoritative flag
 139  Returns   :    current value
 140
 141 =cut
 142
 143 =head2 URL
 144
 145  Title     :    URL
 146  Usage     :    $URL = $Service->URL($url)
 147  Args      :    (optional) string representing a URL
 148  Function  :    get/set service URL endpoint
 149  Returns   :    current value
 150
 151 =cut
 152
 153 =head2 contactEmail
 154
 155  Title     :    contactEmail
 156  Usage     :    $email = $Service->contactEmail($email)
 157  Args      :    (optional) string representing an email address
 158  Function  :    get/set service email address
 159  Returns   :    current value
 160
 161 =cut
 162
 163
 164 =head2 LSID
 165
 166  Title     :    contactEmail
 167  Usage     :    $email = $Service->LSID()
 168  Args      :    none
 169  Function  :    get (readonly) service instance LSID
 170  Returns   :    current value as scalar string
 171
 172 =cut
 173
 174 =head2 registry
 175
 176  Title     :    registry
 177  Usage     :    $regname = $Service->registry([$description])
 178  Function  :    get/set registry
 179  Returns   :    string
 180
 181 =cut
 182
 183 {
 184
 185         # Encapsulated:
 186         # DATA
 187         #___________________________________________________________
 188         #ATTRIBUTES
 189         my %_attr_data =    #                                   DEFAULT         ACCESSIBILITY
 190           (
 191                 authority => [ undef, 'read/write' ],
 192                 name      => [ undef, 'read/write' ],
 193                 type      => [ undef, 'read/write' ],
 194                 input     => [ undef, 'read/write' ]
 195                 ,               # listref of Simple and Collection articles
 196                 output => [ undef, 'read/write' ]
 197                 ,               # listref of Simple and Collection articles
 198                 secondary   => [ undef, 'read/write' ],   # listref of SecondaryArticles
 199                 category    => [ undef, 'read/write' ],
 200                 description => [ undef, 'read/write' ],
 201                 registry      => [ 'MOBY_Central', 'read/write' ],
 202                 XML           => [ undef,          'read/write' ],
 203                 authoritative => [ undef,          'read/write' ],
 204                 URL           => [ undef,          'read/write' ],
 205                 contactEmail  => [ undef,          'read/write' ],
 206                 LSID              => [ undef,                   'read/write']
 207           );
 208
 209         #_____________________________________________________________
 210         # METHODS, to operate on encapsulated class data
 211         # Is a specified object attribute accessible in a given mode
 212         sub _accessible {
 213                 my ( $self, $attr, $mode ) = @_;
 214                 $_attr_data{$attr}[1] =~ /$mode/;
 215         }
 216
 217         # Classwide default value for a specified object attribute
 218         sub _default_for {
 219                 my ( $self, $attr ) = @_;
 220                 $_attr_data{$attr}[0];
 221         }
 222
 223         # List of names of all specified object attributes
 224         sub _standard_keys {
 225                 keys %_attr_data;
 226         }
 227 }
 228
 229 sub new {
 230         my ( $caller, %args ) = @_;
 231         my $caller_is_obj = ref( $caller );
 232         return $caller if $caller_is_obj;
 233         my $class = $caller_is_obj || $caller;
 234         my $proxy;
 235         my $self = bless {}, $class;
 236         foreach my $attrname ( $self->_standard_keys ) {
 237                 if ( exists $args{$attrname} ) {
 238                         $self->{$attrname} = $args{$attrname};
 239                 } elsif ( $caller_is_obj ) {
 240                         $self->{$attrname} = $caller->{$attrname};
 241                 } else {
 242                         $self->{$attrname} = $self->_default_for( $attrname );
 243                 }
 244         }
 245         $self->input(     [] ) unless $self->input;
 246         $self->output(    [] ) unless $self->output;
 247         $self->secondary( [] ) unless $self->secondary;
 248         return $self;
 249 }
 250
 251 sub AUTOLOAD {
 252         no strict "refs";
 253         my ( $self, $newval ) = @_;
 254         $AUTOLOAD =~ /.*::(\w+)/;
 255         my $attr = $1;
 256         if ( $self->_accessible( $attr, 'write' ) ) {
 257                 *{$AUTOLOAD} = sub {
 258                         if ( defined $_[1] ) { $_[0]->{$attr} = $_[1] }
 259                         return $_[0]->{$attr};
 260                 };    ### end of created subroutine
 261 ###  this is called first time only
 262                 if ( defined $newval ) {
 263                         $self->{$attr} = $newval;
 264                 }
 265                 return $self->{$attr};
 266         } elsif ( $self->_accessible( $attr, 'read' ) ) {
 267                 *{$AUTOLOAD} = sub {
 268                         return $_[0]->{$attr};
 269                 };    ### end of created subroutine
 270                 return $self->{$attr};
 271         }
 272
 273         # Must have been a mistake then...
 274         croak "No such method: $AUTOLOAD";
 275 }
 276 sub DESTROY { }
 277 1;