use Bio::Biblio;
  my $biblio = Bio::Biblio->new (-access => 'soap');

    # where to go...
    $DEFAULT_SERVICE = 'http://www.ebi.ac.uk/openbqs/services/MedlineSRS';

    # ...and what to find there
    
    ## TODO: This namespace is no longer valid (check for deprecation or update)
    $DEFAULT_NAMESPACE = 'http://industry.ebi.ac.uk/openBQS';

    my ($self, @args) = @_;
    
    # make a hashtable from @args
    my %param = @args;
    @param { map { lc $_ } keys %param } = values %param; # lowercase keys

    # copy all @args into this object (overwriting what may already be
    # there) - changing '-key' into '_key'
    my $new_key;
    foreach my $key (keys %param) {
	($new_key = $key) =~ s/^-/_/;
	$self->{ $new_key } = $param { $key };
    }

    # finally add default values for those keys who have default value
    # and who are not yet in the object
    $self->{'_location'} = $DEFAULT_SERVICE unless $self->{'_location'};
    $self->{'_namespace'} = $DEFAULT_NAMESPACE unless $self->{'_namespace'};
    $self->{'_destroy_on_exit'} = 1 unless defined $self->{'_destroy_on_exit'};
    unless ($self->{'_soap'}) {
	if (defined $self->{'_httpproxy'}) {
	    $self->{'_soap'} = SOAP::Lite
	                          -> uri ($self->{'_namespace'})
		                  -> proxy ($self->{'_location'},
				            proxy => ['http' => $self->{'_httpproxy'}]);
	} else {
	    $self->{'_soap'} = SOAP::Lite
	                          -> uri ($self->{'_namespace'})
				  -> proxy ($self->{'_location'});
	}
#	$self->{'_soap'}->soapversion (1.2);
    }
}

# -----------------------------------------------------------------------------

#
# objects representing query collections are being destroyed if they
# have attribute '_destroy_on_exit' set to true - which is a default
# value
#

    my $self = shift;
    my $soap = $self->{'_soap'};
    my $destroy = $self->{'_destroy_on_exit'};
    return unless $destroy;
    my $collection_id = $self->{'_collection_id'};
    return unless $collection_id;

    # ignore all errors here
    eval {
	$soap->destroy (SOAP::Data->type (string => $collection_id));
    }
}

#
# some methods must be called with an argument containing a collection
# ID; here we return a proper error message explaining it
#

    my $self = shift;
    my $package = ref $self;
    my $method = (caller(1))[3];
    my $strip_method = $method;
    $strip_method =~ s/^$package\:\://;

    return <<"END_OF_MSG";
Method '$method' works only if its object has a query collection ID.
Perhaps you need to use:
\tBio::Biblio->new(-collection_id => '1234567')->$strip_method;
or to obtain a collection ID indirectly from a query method:
\tBio::Biblio->new->find ('keyword')->$strip_method;
END_OF_MSG
}
    
#
# some methods do not work with older SOAP::Lite version; here we
#return message explaining it
#

    my $self = shift;
    my $method = (caller(1))[3];

    return <<"END_OF_MSG";
Method '$method' works only with SOAP::Lite
version 0.52 and newer (the problem is with returning a boolean value from the server).
END_OF_MSG
}

#
# some controlled vocabulary methods needs two parameters; here we
# return message explaining it
#

    my $self = shift;
    my $method = (caller(1))[3];

    return <<"END_OF_MSG";
Method '$method' expects two parameters: vocabulary name and a value.
END_OF_MSG
}

#
# some controlled vocabulary methods needs a vocabulary name; here we
# return message explaining it
#

    my $self = shift;
    my $method = (caller(1))[3];

    return <<"END_OF_MSG";
Method '$method' expects vocabulary name as parameter.
END_OF_MSG
}

# 
# return a copy of a given array, with all its elements replaced
# with the SOAP-Data objects defining elements type as 'string'
#

    my ($ref_input_array) = @_;
    my (@result) = map { SOAP::Data->new (type => 'string', value => $_) } @$ref_input_array;
    return\@ result;
}
    
# ---------------------------------------------------------------------
#
#   Here are the methods implementing Bio::DB::BiblioI interface
#   (documentation is in Bio::DB::BiblioI)
#
# ---------------------------------------------------------------------

   my ($self) = @_;
   $self->{'_collection_id'};

   my ($self) = @_;
   my $soap = $self->{'_soap'};
   my ($collection_id) = $self->{'_collection_id'};
   if ($collection_id) {
       $soap->getBibRefCountOfCollection (SOAP::Data->type (string => $collection_id))->result;
   } else {
       $soap->getBibRefCount->result;
   }
}

# try: 12368254 (it's a Bioperl article)

   my ($self, $citation_id) = @_;
   $self->throw ("Citation ID is expected as a parameter of method 'get_by_id'.")
       unless $citation_id;
   my $soap = $self->{'_soap'};
   $soap->getById (SOAP::Data->type (string => $citation_id))->result;

   my ($self, $keywords, $attrs) = @_;
   my (@keywords, @attrs);

   # $keywords can be a comma-delimited scalar or a reference to an array
   if ($keywords) {
       my $ref = ref $keywords;
       @keywords = split (/,/, $keywords) unless $ref;
       @keywords = @$keywords if $ref =~ /ARRAY/;
   }
   $self->throw ("No keywords given in 'find' method.\n")
       unless (@keywords);

   # ...and the same with $attrs
   if ($attrs) {
       my $ref = ref $attrs;
       @attrs = split (/,/, $attrs) unless $ref;
       @attrs = @$attrs if $ref =~ /ARRAY/;
   }

   my $soap = $self->{'_soap'};
   my $collection_id = $self->{'_collection_id'};
   my $new_id;
   if ($collection_id) {
       if (@attrs) {
	   $new_id = $soap->reFindInAttrs (SOAP::Data->name ('arg0')->type (string => $collection_id),
				           SOAP::Data->name ('arg1')->value (&_as_strings (\@keywords)),
				           SOAP::Data->name ('arg2')->value (&_as_strings (\@attrs)))
	       ->result;
       } else {
	   $new_id = $soap->reFind (SOAP::Data->name ('arg0')->type (string => $collection_id),
				    SOAP::Data->name ('arg1')->value (&_as_strings (\@keywords)))
	       ->result;
       }
   } else {
       if (@attrs) {
	   $new_id = $soap->findInAttrs (SOAP::Data->name ('arg0')->value (&_as_strings (\@keywords)),
				         SOAP::Data->name ('arg1')->value (&_as_strings (\@attrs)))
	       ->result;
       } else {
	   $new_id = $soap->find (SOAP::Data->name ('arg0')->value (&_as_strings (\@keywords)))
	       ->result;
       }
   }

   # clone itself but change the collection ID to a new one
   return $self->new (-collection_id        => $new_id,
		      -parent_collection_id => $collection_id);

   my ($self) = @_;
   my $soap = $self->{'_soap'};
   my ($collection_id) = $self->{'_collection_id'};
   $self->throw ($self->_no_id_msg) unless $collection_id;
   $soap->getAllIDs (SOAP::Data->type (string => $collection_id))->result;

   my ($self) = @_;
   my $soap = $self->{'_soap'};
   my ($collection_id) = $self->{'_collection_id'};
   $self->throw ($self->_no_id_msg) unless $collection_id;
   $soap->getAllBibRefs (SOAP::Data->type (string => $collection_id))->result;

   my ($self) = @_;
   my $soap = $self->{'_soap'};
   my ($collection_id) = $self->{'_collection_id'};
   $self->throw ($self->_no_id_msg) unless $collection_id;
   $self->throw ($self->_old_version_msg) if $SOAP::Lite::VERSION lt '0.52';
   $soap->hasNext (SOAP::Data->type (string => $collection_id))->result;

   my ($self) = @_;
   my $soap = $self->{'_soap'};
   my ($collection_id) = $self->{'_collection_id'};
   $self->throw ($self->_no_id_msg) unless $collection_id;
   $soap->getNext (SOAP::Data->type (string => $collection_id))->result;

   my ($self, $how_many) = @_;
   my $soap = $self->{'_soap'};
   my $collection_id = $self->{'_collection_id'};
   $self->throw ($self->_no_id_msg) unless $collection_id;

   unless (defined ($how_many) and $how_many =~ /^\d+$/) {
       $self->warn ("Method 'get_more' expects a numeric argument. Changing to 1.\n");
       $how_many = 1;
   }
   unless ($how_many > 0) {
       $self->warn ("Method 'get_more' expects a positive argument. Changing to 1.\n");
       $how_many = 1;
   }

   my $ra = $soap->getMore (SOAP::Data->type (string => $collection_id),
			    SOAP::Data->type (int    => $how_many))->result;
   $self->{'_collection_id'} = shift @{ $ra };
   $ra;

   my ($self) = @_;
   my $soap = $self->{'_soap'};
   my ($collection_id) = $self->{'_collection_id'};
   $self->throw ($self->_no_id_msg) unless $collection_id;
   $self->{'_collection_id'} = $soap->resetRetrieval (SOAP::Data->type (string => $collection_id))->result;

   my ($self) = @_;
   my $soap = $self->{'_soap'};
   my ($collection_id) = $self->{'_collection_id'};
   $self->throw ($self->_no_id_msg) unless $collection_id;
   $self->throw ($self->_old_version_msg) if $SOAP::Lite::VERSION lt '0.52';
   $soap->exists (SOAP::Data->type (string => $collection_id))->result;

   my ($self) = @_;
   my $soap = $self->{'_soap'};
   my ($collection_id) = $self->{'_collection_id'};
   $self->throw ($self->_no_id_msg) unless $collection_id;
   $soap->destroy (SOAP::Data->type (string => $collection_id));

   my ($self) = @_;
   my $soap = $self->{'_soap'};
   $soap->getAllVocabularyNames->result;

   my ($self, $vocabulary_name, $value) = @_;
   my $soap = $self->{'_soap'};
   $self->throw ($self->_old_version_msg) if $SOAP::Lite::VERSION lt '0.52';
   $self->throw ($self->_two_params_msg)
       unless defined $vocabulary_name and defined $value;
   $soap->contains (SOAP::Data->type (string => $vocabulary_name),
		    SOAP::Data->type (string => $value))->result;

   my ($self, $vocabulary_name, $value) = @_;
   my $soap = $self->{'_soap'};
   $self->throw ($self->_two_params_msg)
       unless defined $vocabulary_name and defined $value;
   $soap->getEntryDescription (SOAP::Data->type (string => $vocabulary_name),
			         SOAP::Data->type (string => $value))->result;

   my ($self, $vocabulary_name) = @_;
   my $soap = $self->{'_soap'};
   $self->throw ($self->_missing_name_msg)
       unless defined $vocabulary_name;
   $soap->getAllValues (SOAP::Data->type (string => $vocabulary_name))->result;

   my ($self, $vocabulary_name) = @_;
   my $soap = $self->{'_soap'};
   $self->throw ($self->_missing_name_msg)
       unless defined $vocabulary_name;
   $soap->getAllEntries (SOAP::Data->type (string => $vocabulary_name))->result;

  bioperl-l@bioperl.org                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

  https://redmine.open-bio.org/projects/bioperl/

 Usage   : print $Bio::DB::Biblio::soap::VERSION;
           print $Bio::DB::Biblio::soap::Revision;

 Usage   : print $Bio::DB::Biblio::soap::DEFAULT_SERVICE;
           print $Bio::DB::Biblio::soap::DEFAULT_NAMESPACE;