NAME

SADI::RDF::Core -- A Perl package for SADI services

DESCRIPTION

This is a module that helps service providers for SADI services do most
of the routine garbage that they need to do to parse and construct
RDF messages for SADI

SYNOPSIS

 use SADI::RDF::Core;
 use SADI::Service::Instance;

 my $service = SADI::Service::Instance->new(
     ServiceName => "helloworld",
     ServiceType => "http://someontology.org/services/sometype",
     InputClass => "http://someontology.org/datatypes#Input1",
     OutputClass => "http://someontology.org/datatypes#Output1",
     Description => "the usual hello world service",
     UniqueIdentifier => "urn:lsid:myservices:helloworld",
     Authority => "helloworld.com",
     Provider => 'myaddress@organization.org',
     ServiceURI => "http://helloworld.com/cgi-bin/helloworld.pl",
     URL => "http://helloworld.com/cgi-bin/helloworld.pl",
 );

 # instantiate a new SADI::Service::Core object
 my $core = SADI::RDF::Core->new;

 # set the Instance for $core
 $core->Signature($service);

 # get the Instance for $core
 $service = $core->Signature();

 # get the service signature 
 my $signature = $core->getServiceInterface;

 # parse the incoming RDF
 $core->Prepare($rdf) || $core->throw( "somehow the input data was improperly formed\n" );

 # get the RDF nodes representing the input, based on input class (from 'new')
 my @inputs = $core->getInputNodes();

 # add output nodes
 $core->addOutputData(
		node  => $resource, # type RDF::Core::Resource
		value => "http://view.ncbi.nlm.nih.gov/protein/12408656",
		predicate =>
"http://sadiframework.org/ontologies/predicates.owl#hasInteractingParticipant"
 );

METHODS

new

$service = SADI::RDF::Core->new(%args);
args:
    Signature L<SADI::Service::Instance> - the SADI service instance we are using (can be set later),
    ServicePredicate(URI) - the predicate that the service will add B<requried>,
    ContentType(string)   - what content-type header should we respond with I<optional>

ServicePredicate

$predURI = $service->ServicePredicate($URI)
get/set the URI of the predicate the service will add to the input data

Prepare

$service->Prepare()

Prepare the incoming data and make sure it is at least parsible;  
Consumes a string of RDF and Returns true if
the incoming message was parsable, though if it isnt then it'll likely
crap-out at some point rather than returning false...

getInputNodes

@nodes = $service->getInputNodes(%args)

get the input passed to the service

args:
     type => URI  ;  optional
returns
     an array of RDF::Core::Resource objects

getLiteralPropertyValues

%values = $service->getLiteralPropertyValues(%args)

get the value for some property of interest (e.g. from input node(s))

args
    property =>  $URI  :  the URI of the predicate for which you want a value
    nodes =>  @nodes   :  the list of nodes (e.g. from getInputNodes)
returns
    hash of {$nodeURI => [$val, $val], ...}

getStatements

my @statements = $core->getStatements(%args);

get an array of RDF::Core::Statements given a subject, object, and/or predicate from the input data

%args
    subject   => the URI of the subject for which you want to retrieve statements for
    object    => the URI of the object for which you want to retrieve statements for
    predicate => the URI of the predicate for which you want to retrieve statements for

B<subject, object and predicate are all optional.>

returns
    a reference to an array of RDF::Core::Statements that match the given subject, object and predicate

getObjects

my @objects = $core->getObjects(%args);

get an array of RDF::Core::Resource nodes given a subject and predicate from the input data

%args
    subject   => the URI of the subject for which you want to retrieve objects for
    predicate => the URI of the predicate for which you want to retrieve objects for

B<subject, object and predicate are all optional.>

returns
    a reference to an array of RDF::Core::Resource that match the given subject and predicate

addOutputData

$service->addOutputData(%args);

add an output triple to the model; the predicate of the triple
is automatically extracted from the ServicePredicate.

You can pass a URI or an RDF::Core::Resource as the "value" argument.  
The node is automatically rdf:typed as the OutputClass if you include
the "typed_as_output" argument as true.

If you pass a "value" that looks like a URI, then this routine WILL ASSUME
THAT YOU WANT IT TO BE AN OBJECT, NOT A SCALAR VALUE.  To over-ride this,
set the boolean "force_literal" argument.  If you pass an RDF::Core::Resource
together with the force_literal argument, the URI of the RDF::Core::Resource
will be extracted and added as a literal value rather than as an object.

args
   
   node => $URI  (the URI string or RDF::Core::Resource of the subject node) OR
           a SADI::Data::OWL::Class (object generated using sadi-generate-datatypes).
           In the event of an OWL class, all other args are ignored.
   
   value => $val  (a string value)
   
   predicate => $URI (optional - the predicate to put between them.  
                      Defaults to $self->ServicePredicate)
   
   typed_as_output => boolean (if present output is rdf:typed as output class)
   
   force_literal => boolean
   
   label => $label (string); label for value node, only if value is a URI
   

serializeInputModel

$xml = $service->serializeInputModel()

if you want access to the raw RDF-XML for the input data, use this method.
Returns you a string with the raw XML

serializeOutputModel

$xml = $service->serializeOutputModel()

if you want access to the raw RDF-XML for the output data (at any point
during the construction of the output), use this method.
Returns you a string with the raw XML

getServiceInterface

 according to the SADI best-practices, the service URL should return the
 interface document if you call it with GET.  Here we auto-generate that
 document.

 $service->getServiceInterface()