head	1.7;
access;
symbols;
locks; strict;
comment	@# @;


1.7
date	2001.08.10.21.13.47;	author leonardr;	state Exp;
branches;
next	1.6;

1.6
date	2001.07.31.17.44.30;	author leonardr;	state Exp;
branches;
next	1.5;

1.5
date	2001.07.31.17.43.59;	author leonardr;	state Exp;
branches;
next	1.4;

1.4
date	2001.07.31.17.37.57;	author leonardr;	state Exp;
branches;
next	1.3;

1.3
date	2001.07.28.01.47.33;	author stack;	state Exp;
branches;
next	1.2;

1.2
date	2001.07.28.01.36.24;	author stack;	state Exp;
branches;
next	1.1;

1.1
date	2001.07.27.23.06.06;	author stack;	state Exp;
branches;
next	;


desc
@@


1.7
log
@New permission checking method, exposed by XML-RPC, to get all the projects in which a user has an action.
@
text
@<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
  <title>Helm Services: XML-RPC</title>
   
</head>
  <body>
<h1>Helm Services: XML-RPC</h1>
<b>Author</b>: <a href="mailto:stack@@collab.net">St.Ack</a>
<br>
<b>Date</b>: $Date: 2001/07/31 17:44:30 $<br>

<h2>Introduction</h2>

<p>Hitting a page upon startup initializes the Helm XML-RPC service,
which allows integrated components to access Helm data without having
to know about the structure of the database. Currently there are two
Helm XML-RPC handlers, the <i>User Information</i> handler ("user")
and the <i>Permission Checking</i> handler ("permission"). This
feature is currently in the HEAD and slated for the 1.2 Tigris
release.<br>

<h2>General XML-RPC Notes</h2>

<p>The Helm XML-RPC service is an instance of the Turbine
XmlRpcService. Read the
<code>$SANDBOX/conf/TurbineResources.properties</code> file to learn
what handlers are running. The port on which the service runs is
available from the $XMLRPC_PORT environment variable.<br>

<p>The Helm XML-RPC API has <a
href="http://helm.tigris.org/source/browse/helm/tests/xmlrpc/TestXMLRPCClient.java?rev=1">
java</a> and <a
href="http://helm.tigris.org/source/browse/helm/tests/xmlrpc/TestXMLRPCClient.pl">
perl</a> test/sample clients.

<p>There is no notion of a null value in the XML-RPC spec. nor the
passing of exceptions: Exceptions show in the java client as a general
exception w/ the message string descriping the server side exception
while in the perl Frontier::Client, an exception will cause the
calling of the 'die' function. &nbsp;Because of these constraints, the
server should only throw exceptions in the catastrophic case and the
server will return empty vectors, hashes, and strings though the
proper answer to a particular permission question should be an
exception proclaiming non-existant user.  &nbsp;Here is how the perl
client renders exceptions via the 'die' function:<br>

<br>
<blockquote>

  <pre>[stack@@marx xmlrpc]$ ./TestXMLRPCClient.pl --action=userInfoFromID --auth=euphrates --url=http://localhost:16500 10<br>Fault returned from XML RPC Server, fault code Frontier::RPC2::Integer=SCALAR(0x83d201c): Frontier::RPC2::String=SCALAR(0x820d73c)</pre>

  <pre>[stack@@marx xmlrpc]$ java TestXMLRPCClient userInfoFromID<br>http://localhost:16500 euphrates 10<br>helma.xmlrpc.XmlRpcException: java.lang.Exception:<br>org.tigris.helm.DoesNotExist: User with ID 10 does not exist<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; at helma.xmlrpc.XmlRpcClient$Worker.execute(XmlRpcClient.java:144)<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; at helma.xmlrpc.XmlRpcClient.execute(XmlRpcClient.java:68)<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; at TestXMLRPCClient.userInfoFromID(TestXMLRPCClient.java:199)<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; at TestXMLRPCClient.processCommand(TestXMLRPCClient.java:136)<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; at TestXMLRPCClient.main(TestXMLRPCClient.java:101)<br></pre>
</blockquote>

<h2>Business object representations</h2>

<p>All handlers represent a user as an XML-RPC hash containing the
following keys: "userID", "loginName", "realName", and "email".

<p>All handlers represent a project as an XML-RPC hash containing the
following keys: "id", "name", and "wordMark".

<h2>The User Information Handler</h2>

<p>As of this writing, you can call the following methods on the
user handler:

<ul>
<li>hash user.getUserInfo(string auth, int id): Get user info by passing in
a Helm user ID.

<li>hash user.getUserInfo(string auth, string domainName, string
loginName): Get user info by passing in their login name and the
domain to which they belong..

<li>array user.getUserInfo(string auth, array userIDs): A batch operation
which takes an array of userIDs and returns an array of user
representations.

<li>boolean user.isValidLogin(string auth, string domainname, string
loginname, string password): Returns true iff the given password is
valid for the named user.

</ul>

<h2>The Permission Handler</h2>

<p>As of this writing, you can call the following methods on the
permission handler:

<ul>

<li>array permission.getPermissionSet(string auth, int userID, int projectID,
array actionsToCheck): Returns that subset of the given actions which
the identified user holds (in any resource) in the identified
project. Actions are given as strings.

<li>array permission.getResourcesForAction(string auth, string
domainName, string projectName, string userName, string action):
Returns the resources in which the named user has the named action in
the named project.

<li>array permission.getUsersWithAction(string auth, int projectID,
string action): Returns descriptions of all the users who have the
given action (in any resource) in the identified project.

<li>array permission.getProjectsWithAction(string auth, int userID
string action): Returns descriptions of all the projects in which the
given user has the given action (in any resource).

</ul>

<h2>Troubleshooting</h2>

<p>Check the server source code for methods available. &nbsp;The
clients may not be up-to-date. All handler code is in the <code><a
href="http://helm.tigris.org/source/browse/helm/java/org/tigris/helm/tool/handler/">
org.tigris.helm.tool.handler</a> </code> package.

<p>Make sure to hit the home page after sandbox start up; this is
needed to make the XML-RPC service start.<br>

    </body>
    </html>
@


1.6
log
@Still more cleanup.
@
text
@d11 1
a11 1
<b>Date</b>: $Date: 2001/07/31 17:43:59 $<br>
d61 3
d107 4
@


1.5
log
@More cleanup.
@
text
@d11 1
a11 3
<b>Date</b>: $Date: 2001/07/31 17:37:57 $<br>
<small>$Id: peerport.html,v 1.4 2001/03/20 21:53:32 brian Exp $</small>

d115 1
a115 1
needed to make the XML-RPC service star.<br>
@


1.4
log
@Brought API description up-to-date.
@
text
@d11 3
a13 1
<b>Date</b>: $Date: 2001/07/28 01:47:33 $<br>
d16 7
a22 3
Hitting a page upon startup initializes helm XML-RPC services. &nbsp;Currently
there is only one helm XML-RPC service, the <i>Permission Checking</i> service.
&nbsp;This feature is currently in the HEAD and slated for the 1.2 tigris
d26 24
a49 17
The helm XML-RPC service is a subclass of the turbine XmlRpcService. Read
the <code>$SANDBOX/conf/TurbineResources.properties</code> file to learn
what services are running and on what ports.<br>

There are <a href="http://helm.tigris.org/source/browse/helm/tests/xmlrpc/TestXMLRPCClient.java?rev=1">
java</a>
  and <a href="http://helm.tigris.org/source/browse/helm/tests/xmlrpc/TestXMLRPCClient.pl">
perl</a>
  test/sample clients. &nbsp;There is no notion of a null value in the XML-RPC
spec. nor the passing of exceptions: Exceptions show in the java client as
a general exception w/ the message string descriping the server side exception
while in the perl Frontier::Client, an exception will cause the calling of
the 'die' function. &nbsp;Because of these constraints, the server should
only throw exceptions in the catastrophic case and the server will return
empty vectors, hashes, and strings though the proper answer to a particular
permission question should be an exception proclaiming non-existant user.
&nbsp;Here is how the perl client renders exceptions via the 'die' function:<br>
d52 1
d54 1
d56 1
a56 3
  </blockquote>
  <h1></h1>
  <p>  </p>
d60 2
a61 2
<p>The handlers represent a user as an XML-RPC hash containing the
keys: "userID", "loginName", "realName", and "email".
d112 1
a112 1
clients may not be up-to-date. &nbsp;Check the <code><a
d116 2
a117 2
<p>Make sure to hit the home page after start up; this is needed to
make the XML-RPC service startup.<br>
a118 2
    <hr><small>$Id: permissions.html,v 1.6 2001/07/18 21:29:05 leonardr Exp
$</small>
@


1.3
log
@Added list of questions you can ask perm. checker.
@
text
@d11 2
a12 1
<b>Date</b>: $Date$<br>
d18 1
d23 1
a23 1
<h2>The Permission Checking Service</h2>
d36 1
a36 1
&nbsp;Here is how the perl client rendors exceptions via the 'die' function:<br>
d44 62
a105 18
As of this writing, you can ask the following questions of the permission
server:<br>
  <blockquote>Get id, user name, real name, and email of a user by passing
in an id.<br>
Get id, user name, real name, and email of a list of users by passing in
a list of ids.<br>
Get id, user name, real name, and email of a user by passing domain and login
name.<br>
Test if the login is valid by passing domain, user name and password.<br>
etc.,<br>
    </blockquote>
Check the server source code for methods available. &nbsp;The clients may
not be up-to-date. &nbsp;Check the <code><a href="http://helm.tigris.org/source/browse/helm/java/org/tigris/helm/tool/handler/">
org.tigris.helm.tool.handler</a>
    </code> package.<br>
    <h2>Troubleshooting</h2>
Make sure to hit the home page after start up; this is needed to make the
XML-RPC service startup.<br>
@


1.2
log
@Fill in notes on the permission checking xmlrpc service.
@
text
@d42 11
d56 2
a57 2
  </code> package.<br>
  <h2>Troubleshooting</h2>
d60 1
a60 1
  <hr><small>$Id: permissions.html,v 1.6 2001/07/18 21:29:05 leonardr Exp
d62 2
a63 2
  </body>
  </html>
@


1.1
log
@Doc. on helm xmlrpc service (Place-holder for moment).
@
text
@d13 4
a16 1
Place-holder<br>
d18 3
a20 1
Place-holder<br>
d22 31
a52 6
Place-holder<br>
<h1></h1>
<p>  </p>
<hr><small>$Id: permissions.html,v 1.6 2001/07/18 21:29:05 leonardr Exp $</small>
</body>
</html>
@

