/ 
RDF-Server-0.08
River stage zero No dependents
/ RDF::Server

NAME

RDF::Server - toolkit for building RDF servers

SYNOPSIS

Build your own package:

package My::Server;

use RDF::Server;
with 'MooseX::Getopt';

interface 'REST';
protocol  'HTTP';
semantic  'Atom';   
               
render xml => 'Atom';
render rss => 'RDF';
           
# Run server (if daemonizable):
                       
my $daemon = My::Server -> new( ... );
    
$daemon -> run();

Build your server class at run-time:

use RDF::Server ();

my $class = RDF::Server -> build_from_config({
    interface => 'REST',
    protocol => 'HTTP',
    semantic => 'Atom',
    renderers => { 
        xml => 'Atom',
        rss => 'RDF'
    },
    with => [qw(
        MooseX::Getopt
    )]
});

my $daemon = $class -> new( ... );

$daemon -> run();

DESCRIPTION

RDF::Server provides a flexible framework with which you can design your own RDF service. By dividing itself into several areas of responsibility, the framework allows you to mix and match any capabilities you need to create the service that fits your RDF data and how you need to access it.

The framework identifies four areas of responsibility:

Protocol

The protocol modules manage the outward facing part of the framework and translating the requested operation into an HTTP::Request object that is understood by any of the interface modules. Conversely, it translates the resulting HTTP::Response object into the form required by the environment in which the server is operating.

For example, the Embedded protocol provides a Perl API that can be used by other modules without having to frame operations in terms of HTTP requests and responses.

The methods expected of protocol modules are defined in RDF::Server::Protocol. The outward-facing API is dependent on the environment the server is expected to operate within.

Available protocols in the standard distribution: RDF::Server::Protocol::Embedded, RDF::Server::Protocol::HTTP.

Interface

The interface modules define how the HTTP requests are translated into operations on various handlers that manage different aspects of the RDF triple store.

Semantic

The semantic modules define the meaning attached to and information contained in the various documents and the heirarchy of resources available through the interface modules. Most of the content handlers are attached to a particular semantic.

The available semantics are: RDF::Server::Semantic::Atom, RDF::Server::Semantic::RDF.

Formatters

The same information can be rendered in several different formats. The format modules manage this rendering.

The available formatters are: RDF::Server::Formatter::Atom, RDF::Server::Formatter::JSON, RDF::Server::Formatter::RDF.

SERVER CONFIGURATION

An RDF::Server server is configured in a two-step process. The initial configuration determins the fundamental behavior of the server by bringing together the appropriate protocol, interface, and semantic roles. The second phase then configures the various information needed for these roles to perform.

The initial configuration can be done either as a Perl package and read at compile time or built at run time using a static method. The run time option can be as flexible as the Perl package method, but you will need to use roles to extend server functionality.

Building a Package

When you use RDF::Server in a package other than main, it will have Moose import into the package and set itself as the package's superclass. It will also import the various class methods detailed below.

As shown in the synopsis:

package My::Server;

use RDF::Server;
with 'MooseX::Getopt';

interface 'REST';
protocol  'HTTP';
semantic  'Atom';

render xml => 'Atom';
render rss => 'RDF';

This sets up the various roles needed to create a complete server.

With the addition of a run time option for configuring this information, rendering information can also be set at run time after the class has been defined, using the set_renderer method.

Building from Configuration

If you use RDF::Server but don't allow its import method to be called, then you can use its static methods to build a class at run time based on a configuration file or other information determined at run time.

As shown in the synopsis:

use RDF::Server ();

my $class = RDF::Server -> build_from_config(
    interface => 'REST',
    protocol => 'HTTP',  
    semantic => 'Atom',
    renderers => {
        xml => 'Atom',
        rss => 'RDF'
    },
    with => [qw(
        MooseX::Getopt
    )],
    port => '8000',
);

The build_from_config static method will construct a class with the appropriate roles based on the configuration information passed in.

Any information that isn't associated with the interface, protocol, semantic, renderers, or with keys is cached and serves as the default values when an object of the class is instantiated. In the above example, the default port is changed to 8000 instead of the usual default of 8080.

STATIC METHODS

new
build_from_config
set_renderer ($extension, $class)

Each class has a class-global mapping of resource extension to rendering class. In addition to allowing renderers to be set at compile time via the render method, this method can be called at run time to modify the mapping.

CLASS METHODS

In addition to the methods exported by Moose, several helper methods are exported when you use RDF::Server. These can be used to easily specify the interface or protocol role if the name is ambiguous.

By default, these helpers will search for the appropriate class by prepending the appropriate RDF::Server:: namespace. You may override this by prepending + to the class name.

The class will be applied to your class as a role. The helper will also make sure that the class provides the appropriate role.

interface

The interface defines how HTTP requests are mapped to actions on resources.

Available interfaces: REST.

protocol

The protocol is how the RDF server communicates with the world.

Available protocols: Embedded, HTTP. FCGI is experimental. (Apache2 is on the TODO list.)

semantic

The server semantic determines how the RDF stores are structured and presented in documents by managing how the handler is configured.

Available semantics: Atom, RDF.

render

The interface maps file types to formatters using the mappings defined by the render method.

OBJECT METHODS

formatter

This will return the formatter for a particular file format as defined by the render method.

CONFIGURATION

default_rendering

This determines the default file format when none is provided. The file format should map to a formatter defined by the render method in the class definition.

handler

This object is used by the interface to find the proper handler for a request. This object must inherit from RDF::Server::Handler.

The server semantic can redefine the handler type and provide a way to configure the handler from a configuration file or Perl data structure.

NAMESPACE DESIGN

The RDF::Server namespace is divided into these broad areas:

Protocol

Modules in RDF::Server::Protocol provide the interface with the world. Examples include HTTP, Apache/mod_perl, and FastCGI.

Interface

RDF::Server::Interface modules determine the type of URI and HTTP method management that is used. RDF::Server comes with a REST interface.

Semantic

RDF::Server::Semantic modules manage the configuration and interpretation of URIs once the Interface module has passed the request on. RDF::Server comes with an Atom semantic of URI heirarchies and configuration.

Formatter

RDF::Server::Formatter modules translate the internal data structures to particular document types. The formatter for a request is selected by the Interface module.

Model

RDF::Server::Model modules interface between the Semantic and Formatter modules and the backend triple store.

Resource

RDF::Server::Resource modules represent particular resources and associated data within a triple store.

SEE ALSO

Moose, RDF::Server::Formatter, RDF::Server::Interface, RDF::Server::Model, RDF::Server::Protocol, RDF::Server::Resource, RDF::Server::Semantic.

BUGS

There are bugs. The test suite only covers a little over 90% of the code. Bugs may be reported on rt.cpan.org or by e-mailing bug-RDF-Server at rt.cpan.org.

AUTHOR

James Smith, <jsmith@cpan.org>

LICENSE

Copyright (c) 2008 Texas A&M University.

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.