This module attempts to make Entrez Utilities SOAP responses as
user-friendly and intuitive as possible. These responses can be
complex structures with much useful data; but users will generally
desire the values of some key fields. The
Result object provides
access to all response values via systematically named accessor
methods, and commonly used values as convenience methods. The 'raw'
SOAP message (a
SOAP::SOM object as returned by
SOAP::Lite) is
also provided.
Convenience accessors
If a list of record ids is returned by the call, ids() will return these as
an array reference:
@seq_ids = $result->ids;
The total count of returned records is provided by count():
$num_recs = $result->count;
If usehistory was specified in the SOAP call, the NCBI-assigned web
environment (that can be used in future calls) is available in
webenv, and the query key assigned to the result in query_key:
$next_result = $fac->efetch( -WebEnv => $result->webenv,
-QueryKey => $result->query_key );
Walking the response
This module uses AUTOLOAD to provide accessor methods for all response data.
Here is an example of a SOAP response as returned by a method() call off the
SOAP::SOM object:
D5 x $result->som->method
0 HASH(0x2eac9a4)
'Count' => 148
'IdList' => HASH(0x4139578)
'Id' => 100136227
'QueryKey' => 1
'QueryTranslation' => 'sonic[All Fields] AND hedgehog[All Fields]'
'RetMax' => 20
'RetStart' => 0
'TranslationSet' => ''
'TranslationStack' => HASH(0x4237b4c)
'OP' => 'GROUP'
'TermSet' => HASH(0x42c43bc)
'Count' => 2157
'Explode' => 'Y'
'Field' => 'All Fields'
'Term' => 'hedgehog[All Fields]'
'WebEnv' => 'NCID_1_150423569_130.14.22.101_9001_1262703782'
Some of the data values here (at the tips of the data structure) are
actually arrays of values ( e.g., the tip IdList = Id> ), other
tips are simple scalars. With this in mind, Result accessor methods work as
follows:
Data values (at the tips of the response structure) are acquired by calling a method with the structure keys separated by underscores (if necessary):
$query_key = $result->QueryKey; # $query_key == 1
$ids = $result->IdList_Id; # @$ids is an array of record ids
Data
sets below a particular node in the response structure can
also be obtained with similarly constructed method names. These
'internal node accessors' return a hashref, containing all data leaves
below the node, keyed by the accessor names:
$data_hash = $result->TranslationStack
D3 x $data_hash
0 HASH(0x43569d4)
'TranslationStack_OP' => ARRAY(0x42d9988)
0 'AND'
1 'GROUP'
'TranslationStack_TermSet_Count' => ARRAY(0x4369c64)
0 148
1 148
2 2157
'TranslationStack_TermSet_Explode' => ARRAY(0x4368998)
0 'Y'
1 'Y'
'TranslationStack_TermSet_Field' => ARRAY(0x4368260)
0 'All Fields'
1 'All Fields'
'TranslationStack_TermSet_Term' => ARRAY(0x436c97c)
0 'sonic[All Fields]'
1 'hedgehog[All Fields]'
Similarly, the call $result-TranslationStack_TermSet > would
return a similar hash containing the last 4 elements of the example
hash above.
Creating accessors is somewhat costly, especially for fetch responses
which can be deep and complex (not unlike BioPerl
developers). Portions of the response tree can be ignored by setting
-prune_at_node to a arrayref of nodes to skip. Nodes should be
specified in
SOAP::SOM format, e.g.
...::Result->new( -prune_at_nodes => ['//GBSeq_references'] );
Accessor creation can be skipped altogether by passing -no_parse =
1> to the Result constructor. This is recommended if a result is
being passed to a
Bio::DB::SoapEUtilities::FetchAdaptor. The original SOAP
message with all data is always available in $result-som>.
Other methods
accessors()
An array of available data accessor names. This
contains only the data "tips". The internal node accessors are
autoloaded.
ok()
True if no SOAP fault.
errstr()
Returns the SOAP fault error string.
som()
The original SOAP::SOM message.
util()
The EUtility associated with the result.
sub parse_methods
{ my $self = shift;
my ($alias_hash, $prune_at_nodes) = @_;
my @methods = keys %{$self->som->method};
my %methods;
foreach my $m (@methods) {
_traverse_methods($m, '/', '', $self->som,\% methods, $self->{'_accessors'}, $prune_at_nodes);
}
if ($alias_hash && ref($alias_hash) eq 'HASH') {
for (keys %$alias_hash) {
if ($methods{ $$alias_hash{$_} }) {
$methods{$_} = $methods{ $$alias_hash{$_} };
push @{$self->{_accessors}}, $_;
}
}
}
if ($methods{Count}) {
push @{$self->{'_accessors'}}, 'count';
for (ref $methods{Count}) {
/^$/ && do {
$methods{count} = $methods{Count};
last;
};
/ARRAY/ && do {
$methods{count} = $methods{Count}->[0];
last;
};
}
}
else {
my @toplev = keys %{$self->som->method};
my ($set) = grep /^.*?S(et|um)$/, @toplev;
if ($set) {
$methods{count} = 0;
my $stem = ($set =~ /(?:DocSum|LinkSet)/ ? "//Body/".$self->result_type."/*" :
"//$set/*");
foreach ($self->som->valueof($stem)) {
$methods{count}++;
}
}
push @{$self->{'_accessors'}}, 'count';
}
$self->_set_from_args(\% methods,
-methods => $self->{'_accessors'},
-case_sensitive => 1,
-create => 1 );
return $self;} | sub _traverse_methods
{ my ($m, $skey, $key, $som, $hash, $acc, $prune) = @_;
if ($prune) {
foreach (@$prune) {
return if "$skey\/$m" =~ /^$_/;
}
}
my $val = $som->valueof("$skey\/$m");
for (ref $val) {
/^$/ && do {
my @a = $som->valueof("$skey\/$m");
my $M = $m;
$M =~ s/([-_])([a-zA-Z0-9])/\u$2/g;
my $k = ($key ? "$key\_" : "").$M;
push @{$acc}, $k;
if (@a == 1) {
$$hash{$k} = $a[0];
}
else {
$$hash{$k} =\@ a;
}
return;
};
/HASH/ && do {
foreach my $k (keys %$val) {
my $M = $m;
$M =~ s/([-_])([a-zA-Z0-9])/\u$2/g;
_traverse_methods( $k, "$skey\/$m",
($key ? "$key\_" : "").$M,
$som, $hash, $acc, $prune );
}
return;
};
do {
Bio::Root::Root->throw("SOAP::SOM parse error : please contact the mailing list");
};
}} | The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _