The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XDI-0.05
River stage zero No dependents
++
/ XDI::Message

NAME

XDI::Message - Message object for XDI client

VERSION

Version 0.01

SYNOPSIS

        use XDI;
        
        my $xdi = XDI->new('=tester');
        my $c = $xdi->connect({ target => '=markus', secret => "foosh"});
        $msg = $c->message({link_contract => '=!91F2.8153.F600.AE24'});
        $msg->add('(=markus/+friend/=tester)');
        $c->post($msg);

EXPORTS

XDI::Message

XDI::Message automatically contructs the XDI message 'envelope' and let's the user enter queries in the XDI statement format. Queries or operations available to the user are the common CRUD methods ($get,$mod,$add,$del in XDI syntax). Multiple statements can be included in a message, but they must all be of the same operation type; ie: no mixing $get and $mod in the same message.

XDI statements in a message do not have an order of execution and currently a single failed statement will roll back the entire message transaction.

The progression from XDI to XDI::Connection to XDI::Message is designed to help construct the message in short, logical steps--not throwing too many configuration options in one blow; however, XDI::Message can stand alone to build the complete XDI message.

Since the message transport is a simple http post, XDI::message can be converted to plain text string and included in a post as the body content.

DESCRIPTION

The XDI::Message module provides an object for constructing XDI messages https://wiki.oasis-open.org/xdi/XdiMessagePatterns

Notation and Conventions

        $xdi    Root object defining identity of querier
        $c      Connection object defining graph target and permissions
        $msg    Message object for XDI messages
        $hash   Reference to a hash of key/attribute values
        $target iname or inumber of the graph which is queried
        $secret Shared secret for access to the I<target> graph
        $graph  From graph
        $from   XDI entity making the query
        $lc     link contract

Usage Outline

Using XDI::Message to construct a self-contained XDI message

XDI messaging syntax is defined at https://wiki.oasis-open.org/xdi/XdiMessagePatterns

        use XDI::Message;
        
        my $msg = new XDI::Message;

Set the ID of the user making the query

        $msg->from("=tester");

Set the ID of the graph that is making the request. If this is being implemented in a peer to peer manner, this will be the same ID as the requestor. In a mediated model where a third party is making the requests on behalf of the requestor (perhaps a link contract management provider that has permissions to create link contracts on the requestor's behalf) this will be a different ID;

        $msg->from_graph('@kynetx');

The target graph is the authoritative graph for the XDI entity that will be queried. When set in the XDI::Message context, it is up to the user to guarantee that the target is a valid XDI target

        $msg->target('@example');

Link contracts are still being developed. Some XDI servers may not yet enforce link contracts, but those servers should ignore the link contract statement so it is always better to include it. In the beginning phases of link contracts, try the target's graph root; ie: '@example' or '=tester'

        $msg->link_contract('@example');

Every graph owner can set the authorization method for their graph, but a shared secret is the default method at this early time of implementation

        $msg->secret('kltpzyxM');

With the configuration done, the client can now configure the operations (CRUD) the user would like to perform on the target graph

SUBROUTINES/METHODS

XDI and it's members support the common PERL OO-style syntax via AUTOLOAD

The first operation method called (get,add,mod,del) will set the XDI::Message object type and all further operations must be of the same type else the method will fail with an error.

Constructor

        $msg = new XDI::Message;
        
        $msg = XDI::Message({from => '=tester', secret => 'kltpzyxM'})

get - Return an XDI graph

Get the whole graph for a user

        $msg->get('=!1111');

Get a portion of the graph

        $msg->get('@example$(+passport)$!(+country)');
        $msg->get('@example+tel$!1');
        
        $msg->get('@example+passport');

add - Add a new element to an XDI graph

Add a literal node

        $msg->add('(@example+work+fax$!(+tel)/!/(data:,+1.801.555.1212))');

Add a new context node

        $msg->add('(@example/()/$*(+tel))');

mod - Modify an existing element of an XDI graph

        $msg->mod('(@example$(+address)$!1$!(+state)/!/(data:,UT))');

del - Delete a portion of an XDI graph

        $msg->del('@example+birthdate');

to_string - Convert the XDI::Message object to a string

        $content = $msg->to_string();

AUTHOR

        Mark Horstmeier <solargroovey@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2007-2012 Kynetx, Inc.

The perl XDI client is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA