File Coverage

blib/lib/RDF/AllegroGraph/Session4.pm

Criterion	Covered	Total	%
statement	24	102	23.5
branch	0	14	0.0
condition			n/a
subroutine	8	25	32.0
pod	5	16	31.2
total	37	157	23.5

package RDF::AllegroGraph::Session4;

use strict;
use warnings;

use base qw(RDF::AllegroGraph::Repository4);

use Data::Dumper;
use feature "switch";

use JSON;
use URI::Escape qw/uri_escape_utf8/;

use HTTP::Request::Common;

=pod

=head1 NAME

RDF::AllegroGraph::Session4 - AllegroGraph session handle for AGv4

=head1 INTERFACE

=cut

sub new {
    my $class = shift;
    return bless { @_ }, $class;
}

=pod

=head2 Methods (additional to L)

=over

=item B

I<$pong> = I<$session>->ping

This method will keep the "connection" with the HTTP server alive (it probably resets the
timeout). In the regular case it should return C, in the error case it will time out.

=cut

sub ping {
    my $self = shift;
    my $resp = $self->{CATALOG}->{SERVER}->{ua}->get ($self->{path} . '/session/ping');
    die "protocol error: ".$resp->status_line.' ('.$resp->content.')' unless $resp->is_success;
    my $result = $resp->content;
    $result =~ s/^\"//; $result =~ s/\"$//;
    return $result;
}

=pod

=item B

I<$session>->rules (" .... prolog rules encoded in LISP, brr ...")

This method parks additional I as rules onto the server. If they can be
parsed correctly, they will be used with the onboard PROLOG reasoner.  See the Franz Prolog tutorial
(./doc/prolog-tutorial.html) for details.

=cut

sub rules {
    my $self = shift;
    my $lisp = shift;
    my $resp = $self->{CATALOG}->{SERVER}->{ua}->post ($self->{path} . '/functor',
						       'Content-Type' => 'text/plain', 'Content' => $lisp);
    die "protocol error: ".$resp->status_line.' ('.$resp->content.')' unless $resp->is_success;
}

=pod

=item B

This method creates one I, in the AGv4 sense. As parameter you have to
pass in

=over

=item the name of the generator:

A symbol, just a simple string, probably better without any fancy characters.

=item how to reach other nodes in the RDF model:

Here you name various predicates (full URIs, no namespaces seem to work) and also whether
these edges should be followed

=over

=item in the C direction, or

=item in the C direction (I in the OWL sense), or

=item in both directions: C

=back

=back

Example:

   $session->generator ('associates',
          { '' => 'bidirectional',
            ''      => 'bidirectional' }
   );

=cut

sub generator {
    my $self   = shift;
    my $symbol = shift;
    my $spec   = shift;

    my @bidirectional;
    my @forward;
    my @reverse;
    foreach my $pred (keys %$spec) {
	given ($spec->{$pred}) {
	    when ('bidirectional') {
		push @bidirectional, $pred;
	    }
	    when ('forward') {
		push @forward, $pred;
	    }
	    when ('reverse') {
		push @reverse, $pred;
	    }
	}
    }
#    warn Dumper \@undirected;

    my $url = new URI ($self->{path} . '/snaGenerators/' . $symbol);
    $url->query_form (
		      (@bidirectional    ? (undirected => \@bidirectional) : ()),
		      (@forward          ? (objectOf   => \@forward)       : ()),
		      (@reverse          ? (subjectOf  => \@reverse)       : ()),
		      );

    my $resp = $self->{CATALOG}->{SERVER}->{ua}->request (PUT $url);
    die "protocol error: ".$resp->status_line.' ('.$resp->content.')' unless $resp->is_success;
}

=pod

=back

=head2 SNA Convenience Methods

While all of the following can be (and actually are) emulated via C and C
invocations, you might find the following handy:

=over

=item B

I<@members> = I<$session>->SNA_members (I<$start_node>, { I })

This method returns the member nodes which can be reached when starting at a particular node and
when particular edges are followed. That edge specification is the same as for the method
C.

B: Internally an SNA generator is created and - using this method - it will be always
overwritten. So, if you need to query this heavily, it is better to fall back to the low-level
generator method and use that instead of a full specification:

   $session->generator ('intimates',
          { '' => 'bidirectional' });

   @ms = $session->SNA_members ('', 'intimates');

=cut

our $adhoc = 'zwumpelfax'; # you may change it, but under what circumstances, really?

sub _linkage {
    my $self = shift;
    my $spec = shift;

    if (ref ($spec) eq 'HASH') {
	my $linkage = $adhoc;
	$self->generator ($linkage, $spec);
	return $linkage;
    } else {
	return $spec; # it is already a string
    }
}

sub SNA_members {
    my $self  = shift;
    my $start = shift;
    my $spec  = shift;

    my $linkage = _linkage ($self, $spec);
    my @ss = $self->prolog (qq{
   (select (?member)
        (ego-group-member !$start 1 $linkage ?member)
    )
    });
#    warn Dumper \@ss;
    return map {$_->[0] } @ss;
}

sub SNA_ego_group {
    my $self = shift;
    my $start = shift;
    my $spec = shift;
    my $depth = shift;

    return ();
}

sub SNA_path {
    my $self = shift;
    my $start = shift;
    my $stop = shift;
    my $spec = shift;
    my $depth = shift;

    my $linkage = _linkage ($self, $spec);
    my @ss = $self->prolog (qq{
   (select (?path)
      (breadth-first-search-path !$start !$stop $linkage $depth ?path))
    });
    warn "ss ". Dumper \@ss;
    return map { $_->[0] } @ss;
}

# strategy : breadth_first, depth_first, bidirectional

sub SNA_nodal_degree {
    my $self = shift;
    my $node = shift;
    my $spec = shift;

}

sub SNA_nodal_neighbors {
    my $self = shift;
    my $node = shift;
    my $spec = shift;
}

=pod

=item B

I<@cliques> = I<$session>->SNA_cliques (I<$node>, I<$generator>)

This method returns a list of list references to the cliques the node is part of. The generator can
again be one predefined (see C), or an adhoc one (see C).

=cut

sub SNA_cliques {
    my $self = shift;
    my $node = shift;
    my $spec = shift;

    my $linkage = _linkage ($self, $spec);
    my @ss = $self->prolog (qq{
   (select (?clique)
      (clique !$node $linkage ?clique))
    });
#    warn Dumper \@ss;
    return map { $_->[0] } @ss;
}

sub SNA_actor_degree_centrality {
}

sub SNA_actor_closeness_centrality {
}

sub SNA_actor_betweeness_centrality {
}

sub SNA_group_degree_centrality {
}

sub SNA_group_closeness_centrality {
}

sub SNA_group_betweeness_centrality {
}



=pod

=back

=head1 AUTHOR

Robert Barta, C<<  >>

=head1 COPYRIGHT & LICENSE

Copyright 2011 Robert Barta, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.

L

=cut

our $VERSION  = '0.03';

1;

__END__