.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "UR::Service::JsonRpcServer 3pm"
.TH UR::Service::JsonRpcServer 3pm "2014-07-04" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
UR::Service::JsonRpcServer \- A self\-contained JSON\-RPC server for UR namespaces
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use lib \*(Aq/path/to/your/moduletree\*(Aq;
\&    use YourNamespace;
\&
\&    my $rpc = UR::Service::JsonRpcServer\->create(host => \*(Aqlocalhost\*(Aq,
\&                                                 port => \*(Aq8080\*(Aq,
\&                                                 api_root => \*(AqURapi\*(Aq,
\&                                                 docroot => \*(Aq/html/pages/path\*(Aq,
\&                                               );
\&    $rpc\->process();
.Ve
.SH "Description"
.IX Header "Description"
This is a class containing an implementation of a JSON-RPC server to respond to 
requests involving UR-based namespaces and their objects.  It uses Net::HTTPServer
as the web server back-end library.
.PP
Incoming requests are divided into two major categories:
.ie n .IP "http://server:port/""api\-root""/class/Namespace/Class" 4
.el .IP "http://server:port/\f(CWapi\-root\fR/class/Namespace/Class" 4
.IX Item "http://server:port/api-root/class/Namespace/Class"
This is the \s-1URL\s0 for a call to a class metnod on \f(CW\*(C`Namespace::Class\*(C'\fR
.ie n .IP "http://server:port/""api\-root""/obj/Namespace/Class/id" 4
.el .IP "http://server:port/\f(CWapi\-root\fR/obj/Namespace/Class/id" 4
.IX Item "http://server:port/api-root/obj/Namespace/Class/id"
This is the \s-1URL\s0 for a method call on an object of class Namespace::Class with the given id
.SH "Constructor"
.IX Header "Constructor"
The constructor takes the following named parameters:
.IP "host" 4
.IX Item "host"
The hostname to listen on.  This can be an ip address, host name, or undef.
The default value is '0.0.0.0'.  This argument is passed along verbatim to
the Net::HTTPServer constructor.
.IP "port" 4
.IX Item "port"
The \s-1TCP\s0 port to listen on.  The default value is 8080.  This argument is passed
along verbatim to the Net::HTTPServer constructor.
.IP "api_root" 4
.IX Item "api_root"
The root path that the http server will listen for requests on.  The constructor registers
two paths with the Net::HTTPServer with \fIRegisterRegex()\fR for /\f(CW\*(C`api_root\*(C'\fR/class/* and
/\f(CW\*(C`api_root\*(C'\fR/obj/* to respond to class and instance metod calls.
.PP
All other arguments are passed along to the Net::HTTPServer constructor.
.SH "Methods"
.IX Header "Methods"
.ie n .IP "$rpc\->\fIprocess()\fR" 4
.el .IP "\f(CW$rpc\fR\->\fIprocess()\fR" 4
.IX Item "$rpc->process()"
A wrapper to the Net::HTTPServer \fIProcess()\fR method.  With no arguments, this call will
block forever from the perspective of the caller, and process all http requests coming in.
You can optionally pass in a timeout value in seconds, and it will respond to requests
for the given number of seconds before returning.
.SH "Client Side"
.IX Header "Client Side"
There are (or will be) client-side code in both Perl and Javascript.  The Perl code is (will be)
implemented as a UR::Context layer that will return light-weight object instances containing only
class info and IDs.  All method calls will be serialized and sent over the wire for the server
process to execute them.
.PP
The Javascript interface is defined in the file urinterface.js.  An example:
.PP
.Vb 4
\&    var UR = new URInterface(\*(Aqhttp://localhost:8080/URApi/\*(Aq);  // Connect to the server
\&    var FooThingy = UR.get_class(\*(AqFoo::Thingy\*(Aq);  // Get the class object for Foo::Thingy
\&    var thingy = FooThingy.get(1234);  // Retrieve an instance with ID 1234
\&    var result = thingy.call(\*(Aqmethod_name\*(Aq, 1, 2, 3);  // Call $thingy\->method_name(1,2,3) on the server
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Ney::HTTPServer, urinterface.js