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


1.25
date	2001.08.10.14.30.26;	author leonardr;	state Exp;
branches;
next	1.24;

1.24
date	2001.08.07.22.40.45;	author leonardr;	state Exp;
branches;
next	1.23;

1.23
date	2001.08.07.22.37.44;	author leonardr;	state Exp;
branches;
next	1.22;

1.22
date	2001.08.07.22.36.07;	author leonardr;	state Exp;
branches;
next	1.21;

1.21
date	2001.08.07.22.34.32;	author leonardr;	state Exp;
branches;
next	1.20;

1.20
date	2001.08.07.22.17.33;	author leonardr;	state Exp;
branches;
next	1.19;

1.19
date	2001.08.07.22.14.09;	author leonardr;	state Exp;
branches;
next	1.18;

1.18
date	2001.08.07.22.12.38;	author leonardr;	state Exp;
branches;
next	1.17;

1.17
date	2001.08.07.22.11.41;	author leonardr;	state Exp;
branches;
next	1.16;

1.16
date	2001.08.07.22.09.33;	author leonardr;	state Exp;
branches;
next	1.15;

1.15
date	2001.08.07.20.30.36;	author leonardr;	state Exp;
branches;
next	1.14;

1.14
date	2001.08.07.17.23.09;	author dlr;	state Exp;
branches;
next	1.13;

1.13
date	2001.08.07.16.37.27;	author dlr;	state Exp;
branches;
next	1.12;

1.12
date	2001.08.07.16.27.24;	author dlr;	state Exp;
branches;
next	1.11;

1.11
date	2001.08.07.16.10.13;	author dlr;	state Exp;
branches;
next	1.10;

1.10
date	2001.08.07.15.48.48;	author leonardr;	state Exp;
branches;
next	1.9;

1.9
date	2001.08.07.15.47.49;	author leonardr;	state Exp;
branches;
next	1.8;

1.8
date	2001.08.06.21.50.40;	author dlr;	state Exp;
branches;
next	1.7;

1.7
date	2001.08.06.20.18.59;	author dlr;	state Exp;
branches;
next	1.6;

1.6
date	2001.08.02.22.10.15;	author dlr;	state Exp;
branches;
next	1.5;

1.5
date	2001.08.02.22.07.44;	author dlr;	state Exp;
branches;
next	1.4;

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

1.3
date	2001.07.24.23.18.33;	author dlr;	state Exp;
branches;
next	1.2;

1.2
date	2001.07.24.22.54.36;	author dlr;	state Exp;
branches;
next	1.1;

1.1
date	2001.07.24.22.27.41;	author dlr;	state Exp;
branches;
next	;


desc
@@


1.25
log
@Integration documents now have their own directory. Also added a new event propagation architecture document to the new directory.
@
text
@<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>

  <head>
   <title>The Helm Component Integration Guide</title>
  </head>

  <body>
    This document has been <a href="integration/">moved</a>.
  </body>

</html>
@


1.24
log
@I Can't Stop Proofreading!
@
text
@d4 7
a10 4
<head>
 <title>The Helm Component Integration Guide</title>
 <!-- Changed by: Daniel L. Rall, 07-Aug-2001 -->
</head>
d12 1
a12 731
<body>

<h1>The Helm Component Integration Guide</h1>
Daniel Rall &lt;dlr at collab dot net&gt;<br>
Leonard Richardson &lt;leonardr at collab dot net&gt;<br>
<small>$Id: integration.html,v 1.23 2001/08/07 22:37:44 leonardr Exp $</small>

<a name="Abstract"><h2>Abstract</h2></a>

 <p>This guide provides a comprehensive overview of integrating
 independent systems with Helm, and of creating new components
 specifically for use with Helm. The points of integration are
 discussed, as are the pros and cons of integrating an application
 with Helm (versus writing an application specifically for Helm) and
 the ways by which the Helm interface to a component is to be set up
 and configured.

 <p><i>[Note: The following section describes a proposed
 implementation of component integration and configuration for the
 Tigris 1.3 release. Only parts of this system are relevant to
 1.2]</i>

<h2>Table of Contents</h2>

<ol>
 <p><li><a href="#Points of Integration">Points of Integration</a>
 <p><li><a href="#Build vs. Adapt">Build vs. Adapt</a>
 <p><li><a href="#Three Ways of Integrating Components">Three Ways of Integrating Components</a>
 <p><li><a href="#Component Directory Structure">Component Directory Structure</a>
 <p><li><a href="#Adaptor Directory Structure">Adaptor Directory Structure</a>
 <p><li><a href="#Proposed Additions">Proposed Additions</a>
 <p><li><a href="#Conclusion">Conclusion</a>
</ol>

<a name="Points of Integration"><h2>Points of Integration</h2></a>

 <p>Whether an existing piece of software is being integrated into
 Helm, or a new one is being written from scratch as a Helm component,
 there are several major points of integration:

 <ol>
  <p><li><a href="#auth">Authentication</a></li>
  <p><li><a href="#access">Access Control</a></li>
  <p><li><a href="#shared">Shared Objects</a></li>
  <p><li><a href="#callbacks">Callbacks</a></li>
  <p><li><a href="#search">Search</a></li>
  <p><li><a href="#ui">User Interface</a></li>
 </ol>

 <p>To achieve integration with the Helm API, you must make at least
 rudimentary use of Helm's authentication and access control
 mechanisms. The other integration points are optional (though a tight
 integration will require use of all integration points).</p>

 <h3><a name="auth">Authentication</a></h3>

  <p>Authentication of users accessing Helm-based systems usually
  occurs through login via a web-based UI.  The code which currently
  handles this activity is the <a
  href="/apidocs/org/tigris/helm/domain/TLogin.html">TLogin</a>
  servlet, which in turn calls out to the <a
  href="/apidocs/org/tigris/helm/tool/SessionManager.html">SessionManager's
  init() method</a> upon successful user authentication.  Though it
  is possible to plug in other authentication mechanisms (i.e. X.509
  certs), the hook to facilitate this process has not yet been
  clearly defined.  The existing hook for external authentication
  mechanisms is a Helm-specific
  <a href="http://jakarta.apache.org/turbine/">Turbine</a> service
  interface <a
  href="/apidocs/org/tigris/helm/tool/IdentityVerificationService.html">implementation</a>.</p>

 <h3><a name="access">Access Control</h3></a>

  <p>Helm's access control system is both the most flexible and the
  most complex part of the system.  <a
  href="/docs/permissions.html">The permission system</a> has a
  user/role/nested group architecture, which restricts users to the
  operations they are allowed to perform in a given project.

  <p>For an integrated tool to provide permission-controlled
  functionality to each of an installation's projects, it must either
  have some internal notion corresponding to Helm's projects (as
  Scarab does), or a separate application data store must be set up
  for each project via a callback (as is done with CVS and
  Issuezilla).</p>

  <p>You can make permission calls using Helm's AccessControlList
  class (if your component compiles against the Helm JAR) or by using
  Helm's <code>permission</code> <a
  href="services_xmlrpc.html">XML-RPC handler</a>.

 <h3><a name="shared">Shared Objects</h3></a>

  <p>In addition to an access control handler, Helm has an XML-RPC
  handler which lets you obtain information about Helm objects via
  XML-RPC. An integrated tool should obtain all of its project and
  user account information from Helm. This may require storing such
  information in the application's internal format (for instance, if
  there are special application-specific users which do not have Helm
  accounts), which is fine so long as changes to the Helm data are
  always reflected in the application.</p>

  <p>You can get user account information using Helm's
  <code>user</code> <a href="services_xmlrpc.html">XML-RPC
  handler</a>.  Other handlers will be forthcoming.

  <p>As with access control, if your component compiles against the
  Helm JAR, you can use Helm business objects natively.

 <a name="callbacks"><h3>Callbacks</h3></a>

  <p>Every component interfaces to Helm through an implementation of
  the <code>HelmListener</code> interface. Each implemented method of
  a registered <code>HelmListener</code> is called when the
  appropriate Helm event happens; for instance,
  <code>projectDeleted</code> is called after the Helm deletion of a
  project. Any given interface probably needs at least a
  <code>projectAdded</code> and a <code>projectDeleted</code>
  implementation so that the resources for a project can be
  initialized and destroyed.

  <p>Your component's <code>HelmListener</code> will be automatically
  registered with the Helm event handler, provided your <a
  href="#conf.components">components</a> file is properly set up.

 <a name="search"><h3>Search</h3></a>

  <p>A component may specify an implementation of the
  <code>ComponentSearch</code> interface. Implementing a
  <code>ComponentSearch</code> implies implementing configuration
  details regarding what in your component is searchable; the details
  of this have yet to be worked out. <i>[In particular, what about
  indexing?]</i>

 <a name="ui"><h3>User Interface</h3></a>

  <p>Certain parts of Helm iterate over components, looking for a
  specific Velocity template and parsing it if a component provides
  it.

  <ul>

   <p><li>ToolNav.vm 

       <p>Parsed by the Project_Nav template. Provides a link to the
       URL intended to serve as the 'main menu' of the component.

   <p><li>PendingActions.vm
       <p>Parsed by the StartPage servlet. Displays linked descriptions
       of component-specific pending actions for the logged-in user.

   <p><li>Options.vm
       <p>Parsed by the ProjectOptions servlet. Displays a partial
       form allowing options to be set for the component. If a
       component specifies no Options.vm, Helm will generate one using
       that component's HELM_ATTRIBUTE entries (this is actually a
       better idea than making an Options.vm, since it means you don't
       have to keep Options.vm up to date. However, it's there if you
       need it).
  </ul>

<a name="Build vs. Adapt">
 <h2>Build vs. Adapt</h2>
</a>

 <p>Should you build a new Helm component or adapt an existing
 component to the task? It depends on which component you're
 considering adapting, and how tight you want the integration to be.

 <p>There are four features of a component which greatly simplify
 integration of a piece of software with Helm (in fact, all but the
 first one greatly simplify integration with almost anything else, and
 changes to facilitate them will most likely be welcomed by the
 mantainers of the project).  Helm, Turbine, and Torque together give
 you most of the framework you need for a web-based software
 engineering tool, so unless the tool you want to adapt is complicated
 or scores well on more than one of these counts, it may be faster to
 reimplement the same functionality.

<ol>

 <p><li>Does it have a concept of projects (or CVS directories, or
 anything for which in Tigris there is a one-to-one mapping to
 projects), and of associating its artifacts with a particular
 project? (Bonus points for nested projects) Otherwise, you'll have to
 create a data store for each Helm project, and use the wrapper to
 swap in the appropriate one on a per-request basis.

 <p><li>Is it able to go to another piece of software for its user
 authentication? Otherwise, you'll have to add this capability or
 cause your users to suffer a double login. Components with no concept
 of user logins do not have this problem.

 <p><li>Is it able to go to another piece of software for its user
 account information? Otherwise, you'll have to add this capability or
 have your <code>HelmListener</code> vigilantly keep your component's
 internal user representation in sync with Helm's. You should also
 disable or hide that portion of the user account editing information
 which duplicates functionality found in Helm. Components with no
 concept of user accounts do not have this problem.

 <p><li>Is it able to go to an outside piece of software for its access
 control? Otherwise, you'll have to add this capability, have your
 <code>HelmListener</code> keep your component's internal
 representation of user permissions in sync with Helm's, or make do
 with the page-level permission checking provided by your wrapper
 class[es]. It is a lot of work to add pluggable access control to a
 component without introducing an implicit dependency on Helm.

</ol>

<h4>Advantages and Disadvantages of Building</h4>

<p>The advantages of building a component for Helm are tighter
integration and faster development time (versus implementing the same
functionality from scratch, and often versus getting the desired level
of integration between Helm and an existing component). The
disadvantage is that you won't have a standalone component (since it
requires Helm), which may limit your audience.

<p>As you might expect, for adapting an existing component to Helm,
the advantages and disadvantages are largely reversed.

<h4>Advantages of Adaptation</h4>

 <ul>

  <p><li>You get the usage of the existing code base (how much of an
  advantage this actually is depends on the quality of the code and
  the degree to which you plan to support the application in the
  future).

  <p><li>You get the advantage of whatever existing user base the
  component has, and since the component can run standalone that user
  base will probably be larger than it would be if it had Helm as a
  dependency. Larger user base == more development and more bug fixes.

 </ul>

<h4>Disadvantages of Adaptation</h4>

 <ul>

  <p><li>Integration with Tigris will tend to be looser, and in the
  worst case will be little more than a branding wrapper around the
  original functionality.

  <p><li>The adaptor must be kept up to date with functionality added
  to the component. It's not quite fair to put this as a disadvantage
  of adaptation, since this is also true of components written for
  Helm, but it's easier to keep the adaptor up to date when the
  adaptor is in the same place as the code it's adapting.

  <p><li>You will probably have to do work on the component to get it to
  play nicely with Helm, especially if it scores poorly on the four
  points listed above. Depending on how tight you want the integration
  to be, some points may not be relevant (for instance, if page-based
  access control is good enough, you can do all the access control in
  the Helm-dependant wrapper class), but in general, the more
  integration you need, the more work it will take.

  <p><li>The source code for the component may not be available, or you
  might be forbidden from changing it. This means you can't make any
  of the changes that make tight integration easier. Of course, if you
  have to integrate <i>this particular component</i> with Helm,
  writing another component to do the same thing is not an option
  anyway.

 </ul>

<a name="Three Ways of Integrating Components">
 <h2>Three Ways of Integrating Components</h2>
</a>

 <p>There are three different processes which have as their end result
 a component integrated with Helm. This section summarizes each one,
 citing one or more examples, and describing how best to attach a
 component of each type to the major Helm integration points.

 <p>Each process involves writing an adaptor, which is a chunk of
 configuration and Java code which makes your software work with
 Helm. If the Helm adaptor is not included with the component, it
 should be made a project on tigris.org and put into the "adaptors"
 category. The recommended name for a component's adaptor is
 "[component]-helm".

<h3>Writing a servlet-based component specifically for Helm</h3>

 <p><b>Example:</b> <a href="http://nidaba.tigris.org/">Nidaba</a>

 <p>This is the easiest case, since you can design your tool to
 conform to Helm's assumptions, and you can use everything in the Helm
 JAR to implement your tool. If you use Torque to handle your business
 objects (highly recommended), you can also make your database tables
 have foreign keys in Helm tables. Finally, the same package can house
 both your component and its Helm adaptor.

 <h4>How to Implement</h4>

  <ul>

   <p><li><b>Authentication:</b> You get this automatically when your
   servlets subclass HelmServlet (actually, you should subclass
   HelmServlet with a ComponentServlet and have all your servlets
   subclass that). Logging in to Helm will give a user authenticated
   access to your component's servlets.

   <p><li><b>Access Control:</b> You can instantiate and use Helm
   AccessControlList objects directly.

   <p><li><b>Shared Objects:</b> You can use instantiate and use OM
   objects directly.

   <p><li><b>Callbacks:</b> Your <code>HelmListener</code> can reside in
   the same class structure as your component. Your
   <code>HelmListener</code> can call both Helm methods and methods of
   your component.

  </ul>

<h3>Adapting a servlet-based component not written for Helm</h3>

 <p><b>Example:</b> <a href="http://eyebrowse.tigris.org/">Eyebrowse</a>

 <p>You will need to create an adaptor which mediates between your
 component and Helm. This adaptor will contain all the Helm
 configuration for the component, as well as the
 <code>HelmListener</code> implementation for the component.

 <p>You will also need to write one or more wrapper servlets which
 subclass HelmServlet and call the component's servlets. It seems
 possible to do all the wrapping in a single servlet, but that's not
 how Eyebrowse does it so I'm not sure.

 <h4>How to Implement</h4>

  <ul>

   <p><li><b>Authentication:</b> The wrapper classes will subclass
   HelmServlet, so logging in to Helm will give a user authenticated
   access to your component's servlets.

   <p><li><b>Access Control:</b> The wrapper classes can make direct
   AccessControlList calls. Your component must either rely on this or
   make use of an pluggable permission checker.

   <p><li><b>Shared Objects:</b> The wrapper classes can use Helm OM objects
   directly; they must provide some way of giving the neccessary
   information to the component's servlets.

   <p><li><b>Callbacks:</b> Your <code>HelmListener</code> must reside in the
   adaptor component. It can call both Helm methods and methods of
   your component.

 </ul>

<h3>Adapting a non-servlet-based component not written for Helm</h3>

 <p><b>Examples:</b> <a
 href="http://issuezilla.tigris.org/">Issuezilla</a>, CVSWeb, CVS

 <p>This is the most difficult case. It's similar to the previous
 case, with the additional complication that the component does not
 use servlets, and is probably not even written in Java.

 <p>The adaptor will need to subclass the HelmNoodle class; you will
 be using Noodle to wrap the functionality of the
 component. HelmNoodle will check for a particular permission on every
 page access; this permission is specified in the HelmNoodle subclass
 config file and is the permission you must have to use the component
 at all. This will probably not be enough permission checking for your
 component, so you will either have to do page-specific checking in
 the HelmNoodle subclass, or plug Helm's permission checker into an
 abstract permission checker within the component.

 <p>You will need to add rewrite rules into the component's httpd
 configuration which transforms a request for a component page into a
 request for your HelmNoodle subclass.

 <h4>How to Implement</h4>

  <ul>

   <p><li><b>Authentication:</b> The HelmNoodle subclass will subclass
   HelmServlet, so logging in to Helm will give a user authenticated
   access to all your component's pages, wrapped through Noodle. If
   your component, like CVS, does not rely on a Web interface, you
   will need to give it pluggable authentication and write an
   authentication module connecting it to Helm.

   <p><li><b>Access Control:</b> The HelmNoodle subclass can make direct
   AccessControlList calls. Your component must either rely on this or
   make use of an abstract permission checker.

   <p><li><b>Shared Objects:</b> The HelmNoodle subclass can use Helm OM
   objects, but the wrapped application cannot. The subclass will have
   to turn the information represented by a request's OM objects into
   a form usable by the wrapped application.

   <p><li><b>Callbacks</b> Your <code>HelmListener</code> must reside in the
   adaptor. It can call Helm methods, and either call methods of your
   component (if written in Java), or run scripts written to drive
   your component (which should also live in the adaptor).

 </ul>

<a name="Component Directory Structure">
 <h2>Component Directory Structure</h2>
</a>

 <p><b>Note:</b> This is the suggested directory structure for a Java
 servlet application written with Helm in mind. If such an application
 contains its own adaptor (as will usually be the case), you will see
 the adaptor directory structure (described next section) overlaid on
 top of this structure.

 <blockquote>
  <code>
   <pre>
    [component]/
      build/
        build.xml
      htdoc/look/www/
        master/
          [servletname]Tasks.html (for servlets that show task bar)
          [component-specific templates, e.g., email templates]
        includes/
          [servletname]Help.vm (for servlets with sticky help notes)
      java/
        [component Java package]/
          om/
            [component business objects]
          tool/
            [additional objects to place in context]
          [servlet dirs]/
            [.java and .properties file for each servlet]
      sql/
        schema
          [component]-schema.xml
      templates/
         [component Java package]/
           [servlet dirs]/
             [.vm files for each servlet]
      www/
        [component web site files]
        docs/
          [component developer documentation files]
   </pre>
  </code>
 </blockquote>

 <h3>Explanation</h3>

  <p>Using the suggested directory structure allows the component to
  to advantage of the hooks supplied by Helm (and its instance) for
  functional extension.</p>

  <h4><code>build</code> directory</h4>

   <p>The build scripts powering any makefiles scattered throughout the
   component directory hierarchy live here.  Helm uses <a
   href="http://jakarta.apache.org/ant/">Ant</a> as much as possible to
   handle its build; components and adaptors should as well.</p>

  <h4><code>java</code> directory</h4>
 
   <p>Contains the Java source code for your component; servlets and
   tools. We <i>strongly recommend</i> that component implementations
   consist of Java as much as possible.</p>

  <h4><code>sql/schema</code> directory</h4>

    <p>Contains the <a
    href="http://jakarta.apache.org/turbine/torque/">Torque</a> XML
    schema for your component.  References to key values from tables
    in foreign database schemas (such as tables from Helm) are
    currently handled using indices in the component schema.  The plan
    is to add foreign database table support to Torque and its
    DTD.</p>

    <p>We <i>strongly recommend</i> that you use Torque in writing
    components (and web apps in general). It saves a lot of busy work
    and lets you get down to implementing servlets.

   <h4><code>templates/[component Java package]</code> directory</h3>

    <p>Contains Velocity templates for the component's servlets.</p>

   <h4><code>www</code> directory</h4>

    <p>The component's web site for [component].tigris.org. The
    <code>docs</code> subdirectory contains developer
    documentation.</p>

<a name="Adaptor Directory Structure"><h2>Adaptor Directory Structure</h2></a>

 <p><b>Note:</b> If the adaptor comes with the component, then these
 directories are to be found in the component directory tree with the
 rest of the component.

 <blockquote>
  <code>
   <pre>
    [component]-helm/
      build/
        build.sh
        build.xml
      conf/
        [component].ant.properties
        <a href="#conf.components">[0-9][0-9][component].components</a>
        <a href="#conf.servlets">[0-9][0-9][component].servlets</a>
        <a href="#conf.TurbineResources.properties">[0-9][0-9][component].TurbineResources.properties</a> (if needed)
        <a href="#conf.zone.properties">[0-9][0-9][component].zone.properties</a> (if needed)
        <a href="#conf.httpd.conf">[0-9][0-9][component].httpd.conf</a> (if needed)
      data/
        htdoc/www/www/docs/ (component-specific end-user online help pages)
      htdoc/look/www/master/
        [templates for Helm integration]
      java/
        [component Java package]/
          tool/
            adaptor/
              [component]HelmListener.java (suggested location)       
      scripts/
        migration/
          [versionnumber]/
      sql/
        [component Java package]/
          LoadOrder.lst
          [files specified in this, instance, or Helm LoadOrder.lst]
          [importantly, <a href="#sql.Action">SQL for component-specific actions and role assignments</a> and
          <a href="#sql.Attribute">SQL for component-specific attributes</a>.]
   </pre>
  </code>
 </blockquote>

<h3>Explanation</h2>

 <h4><code>conf</code> directory</h4>

  <p>Component-specific configuration to be copied to your Tigris
  instance's <code>site/conf/</code> directory during installation.
  Common Ant variables are specified via a
  <code>[component].ant.properties</code> file.  Configuration for
  provided servlets is added via <code>[two digit
  number]servlets</code>, with a lower number indicating higher
  precendance in final servlets configuration file.</p>

  <ul>
   <p><li><a name="conf.components">conf/[0-9][0-9][component].components:</a>

       <p>This is the file which notifies Helm of the existence of the
       component. Valid attribute settings are the following:

       <ul>

        <p><li><code>component.humanReadableName</code>: Helm will use
        the value of this attribute when displaying the name of the
        component to a user, eg. "CVS Configuration Options".

        <p><li><code>components.[component].current[business object
        type]</code>: Value should be the fully-qualified name of a
        class which will be instantiated using as the key any string
        found in the "[business object type]ID" field in the request.

	<p>For example:
	<code>components.mycomponent.currentMyObject=org.tigris.helm.mycomponent.MyObject</code>
	will, if "myObjectID=3" comes in on a request, cause the
	MyObject instance with ID 3 to be available as
	"currentMyObject" in the context.

        <p>You can also specify "[business object type]" as a value
        for the servlet-specific "requiredBusinessObject" property,
        which will cause an error to occur if a user tries to access
        the servlet without specifying a value for "[business object
        type]ID".

        <p><li><code>components.[component].HelmListener</code>: Value
        should be the fully-qualified name of a class which implements
        the Helm interface <code>HelmListener</code>. Though this item
        is optional, you will need to implement a
        <code>HelmListener</code> to get any kind of meaningful
        integration with Helm.

        <p><li><code>components.[component].ComponentSearch</code>:
        Value should be the fully-qualified name of a class which
        implements the Helm interface
        <code>ComponentSearch</code>. Though this item is optional,
        you will need to implement a <code>ComponentSearch</code> to
        allow your component's artifacts to be searched using Helm's
        unified search.

       </ul>

   <p><li><a name="conf.servlets">conf/[0-9][0-9][component].servlets</a>

       <p>If your component is written using Java servlets, this
       contains the names and classes of the component servlets (or
       the adaptor servlets which wrap them, if there are wrapper
       servlets). Otherwise, it contains the name and class of the
       HelmNoodle subclass which wraps your non-servlet pages.

   <p><li><a name="conf.TurbineResources.properties">conf/[0-9][0-9][component].TurbineResources.properties</a>

       <p>If your application makes use of any Turbine services (either
       built-in services or services written for your application),
       this is the configuration file in which you should name those
       services.

   <p><li><a name="conf.zone.properties">conf/[0-9][0-9][component].zone.properties </a>

       <p>Contains Java properties for your component. Since there is
       no way to change a property beyond editing this file and
       reconfiguring, we recommend using this file for configuration
       settings which are set at install time, and specifying as
       attributes settings which should be changeable from a Web
       interface.
   
   <p><li><a name="conf.httpd.conf">conf/[0-9][0-9][component].httpd.conf</a>

       <p>Contains Apache server configuration information for your
       component. This includes rewrite rules for routing requests for
       a component's non-servlet pages to that component's HelmNoodle
       subclass.
  </ul>


 <h4><code>data</code> directory</h4>

  <p>Initial data files specific to your component.  These should be
  copied to the <code>$SANDBOX/data/</code> directory at installation
  time.  The content under <code>data/htdoc</code> is able to take
  advantage of Helm's remote branding functionality.
  <code>data/htdoc/look/www/master/</code> is for additional master
  templates (another nice hook into Helm).</p>


 <h4><code>sql/[component Java package]</code> directory</h4>

  <p>Scripts to perform initial database population.  The file
  <code>LoadOrder.lst</code> is used as the "callback" hook by Helm's
  <code>create_tigris_database</code> script to specify additional
  files to run for the component.</p>

  <p>A few of the SQL files are especially important for
  components. They are described below.

  <p><li><a name="sql.Action">SQL for component-specific actions and role
  assignments</a>

   <p>To tie your component into Helm's permission system, you will
   probably need to define some new actions. These should go into
   populate_Action.sql.

   <p>To pick good actions, think about the use cases not only for
   your component, but for the general sort of functionality provided
   by that component. Name your actions according to the sort of
   functionality provided by your component (eg. "Issue Tracking",
   "Version Control", "Document") so that another component which
   covers the same ground as your component can use the same
   actions. In the future, one project on a site may be using your
   component while another makes use of a different component to do
   the same thing. In such a case, the same role in the different
   projects should convey the same abilities in each.

   <p>Your actions won't have any effect unless you grant them to
   roles (or unless the users of the site create new roles with your
   actions). For this reason, you need a
   populate_RoleActionResource.sql file as well as
   populate_Action.sql. You can specify the roles by name, using the
   names of the default roles found in Helm's populate_Role.sql, but
   if at all possible it's better to tie your action to one or more
   Helm actions, granting your action to all the roles which have the
   others. This way, a site which gets upgraded to use your component
   will have user-created roles updated in ways that make
   sense. [<i>HELP: This has security implications, but only as
   regards access to the new functionality. Should we not recommend
   this?</i>]

   <p>Note that all of this is separate from the issue of getting your
   component to use Helm's system to do permission checks.

  <p><li><a name="sql.Attribute">SQL for component-specific attributes</a>

   <p>Helm provides an interface for centralized editing of project
   attributes. Your component can specify an attribute which will be
   made part of this interface. The <code>HelmListener</code> for your
   component will be notified of changes to its attributes, as well as
   to Helm attributes (or, if your component already depends on Helm,
   you can just look up the current values of attributes).

   <p>Your attributes should be put in the file
   populate_Attribute.sql. Each attribute has a name, a default value,
   and an action which is to be checked in a project before allowing a
   user to change that attribute for that project.
  </ul>

 <h4><code>templates/[component Java package]/includes</code> directory</h4>

  <p>Contains the template fragments for <a href="#ui">user interface
  integration.</a></p>

<a name="Proposed Additions"><h2>Proposed Additions</h2></a>

 <ul>

  <p><li>The ComponentSearch specification needs to be designed,

  <p><li>Operations-oriented integration points: logging, UNIX user file
  ownership, monitoring interfaces, etc.

  <p><li>Short case studies of integration, in particular with regards
  to permissions (do as separate pages).

  <p><li>Into which integration category does Scarab fall? It's Java
  servlets and the goal is to give it tight integration with Helm in
  the presence of Helm, but also to allow it to operate standalone. A
  new category may be neccessary for this, or a section added to the
  first category.

 </ul>

<a name="Conclusion"><h2>Conclusion</h2></a>

 <p>You should now know the basics of writing components for Helm and
 of integrating foreign components into Helm. Any discoveries or rules
 of thumb made during the integration process should go onto this page
 or a related page.

</body>
</html>@


1.23
log
@Still more rewording.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.22 2001/08/07 22:36:07 leonardr Exp $</small>
d709 1
a709 1
  integration.</p>
d717 1
a717 1
  <p>Operations-oriented integration points: logging, UNIX user file
@


1.22
log
@Corrected combination of link and <pre> tag.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.21 2001/08/07 22:34:32 leonardr Exp $</small>
d566 2
a567 2
        when displaying the name of the component to a user, eg. "CVS
        Configuration Options".
d570 3
a572 3
        type]</code>: The fully-qualified name of a class which should
        be instantiated using as the key any string found in the
        "[business object type]ID" field in the request.
d586 4
a589 4
        <p><li><code>components.[component].HelmListener</code>: The
        fully-qualified name of a class which implements the Helm
        interface <code>HelmListener</code>. Though this item is
        optional, you will need to implement a
d594 6
a599 5
        The fully-qualified name of a class which implements the Helm
        interface <code>ComponentSearch</code>. Though this item is
        optional, you will need to implement a
        <code>ComponentSearch</code> to allow your component's
        artifacts to be searched using Helm's unified search.
d641 1
a641 3
  advantage of Helm's remote branding
  functionality. <code>data/htdoc/www/www/docs/</code> is end user
  documentation for this component, and
@


1.21
log
@Proofreading and implementation of one of the TODO items.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.20 2001/08/07 22:17:33 leonardr Exp $</small>
d539 2
a540 4
          [importantly, <a href="#sql.Action">SQL for
          component-specific actions and role assignments</a> and <a
          href="#sql.Attribute">SQL for component-specific
          attributes</a>.]
@


1.20
log
@Corrected pluralization.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.19 2001/08/07 22:14:09 leonardr Exp $</small>
d180 7
a186 5
 first one greatly simplify integration with almost anything else).
 Helm, Turbine, and Torque together give you most of the framework you
 need for a web-based software engineering tool, so unless the tool
 you want to adapt is complicated or scores well on more than one of
 these counts, it may be faster to reimplement the same functionality.
d256 5
a260 5
  <p><li>The adaptor must be kept up to date with functionality added to
  the component It's not quite fair to put this as a disadvantage,
  since this is also true of components written for Helm, but it's
  easier to keep the adaptor up to date when the adaptor is in the
  same place as the code it's adapting (there's also less of it).
d380 3
a382 1
 component.
d395 2
a396 2
   your component does not rely on a Web interface (eg. CVS), you will
   need to give it pluggable authentication and write an
d401 1
a401 3
   make use of an abstract permission checker. For very basic cases,
   it will suffice to put into the subclass .properties file the name
   of the one action which gates all access to the component.
d431 6
a436 3
      htdoc/look/www/master/
        [servletname]Tasks.html (for servlets that show task bar)
        [component-specific templates, e.g., email templates]
d571 16
a586 1
        <p><li><code>components.[component].humanReadableName</code>:
d709 1
a709 1
 <h4><code>templates/[component Java package]/fragments</code> directory</h4>
d718 4
a721 7
  <p><li>It would be great to allow an app like Nidaba to hook into
  HelmServlet's capability for turning a "currentBusinessObjectID"
  field in the request into an instance of BusinessObject, and also
  for a servlet to specify that it requires such an instance. I'm not
  sure how best to do this, but it will show up as another entry in
  the components file. You can do this in ComponentServlet, but I'd
  rather not duplicate the same functionality in every component.
a725 2
  <p><li>The ComponentSearch specification needs to be designed,

a730 3

  <p>Operations-oriented integration points: logging, UNIX user file
  ownership, monitoring interfaces, etc.
@


1.19
log
@Removed stale TODO option.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.18 2001/08/07 22:12:38 leonardr Exp $</small>
d224 1
a224 1
disadvantages are that you won't have a standalone component (since it
@


1.18
log
@More hardcoded numbers removed.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.17 2001/08/07 22:11:41 leonardr Exp $</small>
a167 1
   <p><li><i>[TODO: This component's place on taskbars.]</i>
@


1.17
log
@Hard-coded numbers are not so good.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.16 2001/08/07 22:09:33 leonardr Exp $</small>
d60 2
a61 2
 mechanisms. The other two integration points are optional (though a
 tight integration will require use of all integration points).</p>
@


1.16
log
@Added the user interface and search as integration points.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.15 2001/08/07 20:30:36 leonardr Exp $</small>
d47 1
a47 1
 there are four major points of integration:
d285 1
a285 1
 component of each type to the four major Helm integration points.
@


1.15
log
@Changed to reflect comments on document.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.14 2001/08/07 17:23:09 dlr Exp $</small>
d54 2
d120 4
a123 4
  <p>Every non-Helm component interfaces to Helm through an
  implementation of the <code>HelmListener</code> interface. Each
  implemented method of a registered <code>HelmListener</code> is
  called when the appropriate Helm event happens; for instance,
d134 37
d559 1
a559 2
       component.  You will need to add a line with the following
       format:
d561 1
a561 1
       <p><tt>[Human-readable name],[component],[Classname of <code>HelmListener</code>]</tt>
d563 19
a581 2
       <p>The first item is what Helm will use when displaying the name
       of the component to a Helm user, eg. "CVS Configuration Options".
d583 1
a583 8
       <p>The second item is the directory underneath $SANDBOX in which
       Helm should look for component-specific templates.

       <p>The third item is the fully-qualified name of a class which
       implements the Helm interface <code>HelmListener</code>. Though
       this item is optional, you will need to implement a
       <code>HelmListener</code> to get any kind of meaningful
       integration with Helm.
d692 2
a693 19
  <p>Certain parts of Helm iterate over components, looking for a
  specific Velocity template and parsing it if a component provides
  it.

  <ul>
   <p><li>PendingActions.vm
       <p>Parsed by the StartPage servlet. Displays linked descriptions
       of component-specific pending actions for the logged-in user.

   <p><li>Options.vm
       <p>Parsed by the ProjectOptions servlet. Displays a partial
       form allowing options to be set for the component. If a
       component specifies no Options.vm, Helm will generate one using
       that component's HELM_ATTRIBUTE entries (this is actually a
       better idea than making an Options.vm, since it means you don't
       have to keep Options.vm up to date. However, it's there if you
       need it).
   <p><li><i>[TODO: This component's place on taskbars.]</i>
  </ul>
d710 1
a710 3
  <p>Search is another point of integration. Components will need to
  provide a search interface and may contribute UI sections to the
  search specification page.
d718 2
a719 2
  <p>Standards for operations-oriented integration points: logging,
  UNIX user file ownership, monitoring interfaces, etc.
@


1.14
log
@Changed wording to make more sense in the case where the "component"
is an existing piece of software.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.13 2001/08/07 16:37:27 dlr Exp $</small>
d34 7
a40 7
 <li><a href="#Points of Integration">Points of Integration</a>
 <li><a href="#Build vs. Adapt">Build vs. Adapt</a>
 <li><a href="#Three Ways of Integrating Components">Three Ways of Integrating Components</a>
 <li><a href="#Component Directory Structure">Component Directory Structure</a>
 <li><a href="#Adaptor Directory Structure">Adaptor Directory Structure</a>
 <li><a href="#Proposed Additions">Proposed Additions</a>
 <li><a href="#Conclusion">Conclusion</a>
d50 4
a53 4
  <li><a href="#auth">Authentication</a></li>
  <li><a href="#access">Access Control</a></li>
  <li><a href="#shared">Shared Objects</a></li>
  <li><a href="#callbacks">Callbacks</a></li>
d61 1
a61 2
 <h3><a name="auth">
  <a href="/apidocs/org/tigris/helm/security/">Authentication</a></a></h3>
d83 2
a84 2
  user/role/nested group architecture, which effectively restricts the
  actions of users by granting them roles in projects.
d94 3
a96 3
  class (if your component includes the Helm JAR) or by using Helm's
  <code>permission</code> <a href="services_xmlrpc.html">XML-RPC
  handler</a>.
d150 6
a155 5
 <li>Does it have a concept of projects, and of associating its
 artifacts with a project? (Bonus points for nested projects)
 Otherwise, you'll have to create a data store for each Helm project,
 and use the wrapper to swap in the appropriate one on a per-request
 basis.
d157 1
a157 1
 <li>Is it able to go to another piece of software for its user
d159 2
a160 1
 cause your users to suffer a double login.
d162 1
a162 1
 <li>Is it able to go to another piece of software for its user
d167 2
a168 1
 which duplicates functionality found in Helm.
d170 1
a170 1
 <li>Is it able to go to an outside piece of software for its access
d196 4
a199 2
  <li>You get the usage of the existing code base (how much of an
  advantage this actually is depends on the quality of the code).
d201 1
a201 1
  <li>You get the advantage of whatever existing user base the
d212 1
a212 1
  <li>Integration with Tigris will tend to be looser, and in the
d216 1
a216 1
  <li>The adaptor must be kept up to date with functionality added to
d222 1
a222 1
  <li>You will probably have to do work on the component to get it to
d230 1
a230 1
  <li>The source code for the component may not be available, or you
d251 3
a253 2
 should be made a subproject of the "adaptors" project on tigris.org.
 The recommended name for a component's adaptor is "[component]-helm".
d270 5
a274 3
   <li><b>Authentication:</b> You get this automatically when your
   servlets subclass HelmServlet. Logging in to Helm will give a user
   authenticated access to all your component's servlets.
d276 1
a276 1
   <li><b>Access Control:</b> You can instantiate and use Helm
d279 1
a279 1
   <li><b>Shared Objects:</b> You can use instantiate and use OM
d282 1
a282 1
   <li><b>Callbacks:</b> Your <code>HelmListener</code> can reside in
d307 3
a309 3
   <li><b>Authentication:</b> The wrapper classes will subclass
   SecureServlet, so logging in to Helm will give a user authenticated
   access to all your component's servlets.
d311 1
a311 1
   <li><b>Access Control:</b> The wrapper classes can make direct
d315 1
a315 1
   <li><b>Shared Objects:</b> The wrapper classes can use Helm OM objects
d319 1
a319 1
   <li><b>Callbacks:</b> Your <code>HelmListener</code> must reside in the
d337 4
a340 2
 page access; this permission is also specified in the config
 file. <i>[Which file?]</i>
d350 1
a350 1
   <li><b>Authentication:</b> The HelmNoodle subclass will subclass
d357 1
a357 1
   <li><b>Access Control:</b> The HelmNoodle subclass can make direct
d363 1
a363 1
   <li><b>Shared Objects:</b> The HelmNoodle subclass can use Helm OM
d368 1
a368 1
   <li><b>Callbacks</b> Your <code>HelmListener</code> must reside in the
d496 4
a499 1
          [importantly, <a href="#sql.Action">populate_Action.sql</a> and <a href="#sql.Attribute">populate_Attribute.sql</a>
d517 1
a517 1
   <li><a name="conf.components">conf/[0-9][0-9][component].components:</a>
d537 1
a537 1
   <li><a name="conf.servlets">conf/[0-9][0-9][component].servlets</a>
d545 1
a545 1
   <li><a name="conf.TurbineResources.properties">conf/[0-9][0-9][component].TurbineResources.properties</a>
d552 1
a552 1
   <li><a name="conf.zone.properties">conf/[0-9][0-9][component].zone.properties </a>
d561 1
a561 1
   <li><a name="conf.httpd.conf">conf/[0-9][0-9][component].httpd.conf</a>
d592 1
a592 1
  <li><a name="sql.Action">SQL for component-specific actions and role
d627 1
a627 1
  <li><a name="sql.Attribute">SQL for component-specific attributes</a>
d649 1
a649 1
   <li>PendingActions.vm
d653 1
a653 1
   <li>Options.vm
d661 1
a661 1
   <li><i>[TODO: This component's place on taskbars.]</i>
d668 1
a668 1
  <li>It would be great to allow an app like Nidaba to hook into
d670 2
a671 1
  field in the request into an instance of BusinessObject. I'm not
d673 5
a677 1
  the components file.
d679 9
a687 2
  <li>Short case studies of integration, in particular with regards to
  permissions (separate pages).
d689 2
a690 2
  <li>Into which category does Scarab fall? A new category may be
  neccessary.
@


1.13
log
@Re-added information from versions 1.7 and 1.8 clobbered during last
leonardr commit (1.9).
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.12 2001/08/07 16:27:24 dlr Exp $</small>
d45 3
a47 3
 <p>Whether a component is being integrated into Helm or being written
 from scratch as a Helm component, there are four major points of
 integration:
@


1.12
log
@Corrected URL.
@
text
@d13 2
a14 2
Leonard Richardson &lt;dlr at collab dot net&gt;<br>
<small>$Id: integration.html,v 1.11 2001/08/07 16:10:13 dlr Exp $</small>
d68 8
a75 5
  servlet.  Though it is possible to plug in other authentication
  mechanisms (i.e. X.509 certs), the hook to facilitate this process
  has not yet been clearly defined.  The existing hook for external
  authentication mechanisms is a Helm-specific <a
  href="http://jakarta.apache.org/turbine/">Turbine</a> service
d96 2
a97 3
  <code>permission</code> XML-RPC handler.  (<a
  href="services_xmlrpc.html"><i>Information on the Helm XML-RPC
  handlers</i></a>)
d111 2
a112 3
  <code>user</code> XML-RPC handler.  (<a
  href="services_xmlrpc.html"><i>Information on the Helm XML-RPC
  handlers</i></a>) Other handlers will be forthcoming.
@


1.11
log
@build.sh deprecated in favor of installing Ant.
@
text
@d14 1
a14 1
<small>$Id: integration.html,v 1.10 2001/08/07 15:48:48 leonardr Exp $</small>
d251 1
a251 1
 <p><b>Example:</b> <a href="http://eyebrowse.tigris.org/">Nidaba</a>
@


1.10
log
@Corrected closing list tag.
@
text
@d6 1
d14 1
a14 1
<small>$Id: integration.html,v 1.9 2001/08/07 15:47:49 leonardr Exp $</small>
a379 1
        build.sh
@


1.9
log
@Integrated (ha ha) component HOWTO into integration doc, and added
many details about how to write and adapt components. Details of 1.3
integration architecture significantly fleshed out.
@
text
@d13 1
a13 1
<small>$Id: integration.html,v 1.6 2001/08/02 22:10:15 dlr Exp $</small>
d40 1
a40 1
</ul>
@


1.8
log
@Added more information on the current state of Authentication
(including SessionManager's init(User) refactoring).
@
text
@d4 671
a674 124
  <head>
    <title>The Systems Integration Guide to the Helm API</title>
    <!-- Changed by: Daniel L. Rall, 06-Aug-2001 -->
  </head>

  <body>
    <h1>The Systems Integration Guide to the Helm API</h1>
    Daniel Rall &lt;dlr at collab dot net&gt;<br>
    Leonard Richardson &lt;leonardr at collab dot net&gt;<br>
    July 30, 2001<br>
    <small>$Id: integration.html,v 1.7 2001/08/06 20:18:59 dlr Exp $</small>

    <h2>Overview</h2>
    <p>This guide provides a comprehensive overview of integrating
      independent systems with Helm via its external API.  Examples
      of live, open source systems which take advantage of this API
      include <a href="http://issuezilla.tigris.org/">IssueZilla</a>
      and <a href="http://scarab.tigris.org/">Scarab</a> (coming
      soon).</p>

    <!--
    <h3>sub topic</h3>
    <blockquote>
      <code>
	<pre>
        </pre>
      </code>
    </blockquote>
    -->

    <h2>Explanation</h2>
    <p>The Helm API is composed of four major pieces:
      <ul>
	<li><a href="#auth">Authentication</a></li>
	<li><a href="#access">Access Control</a></li>
	<li><a href="#shared">Shared Objects</a></li>
	<li><a href="#callbacks">Event-Triggered Callbacks</a></li>
      </ul>
      To achieve integration with the Helm API, use of Helm's
      Authentication and ACL mechanisms is required.</p>

    <h3><a name="auth"></a> 
     <a href="/apidocs/org/tigris/helm/security/">Authentication</a> (?)</h3>

    <p>Authentication of users accessing Helm-based systems usually
    occurs through login via a web-based UI.  The code which currently
    handles this activity is the <a
    href="/apidocs/org/tigris/helm/domain/TLogin.html">TLogin</a>
    servlet, which in turn calls out to the <a
    href="/apidocs/org/tigris/helm/tool/SessionManager.html">SessionManager's
    init() method</a> upon successful user authentication.  Though it
    is possible to plug in other authentication mechanisms (i.e. X.509
    certs), the hook to facilitate this process has not yet been
    clearly defined.  The existing hook for external authentication
    mechanisms is a Helm-specific
    <a href="http://jakarta.apache.org/turbine/">Turbine</a> service
    interface <a
    href="/apidocs/org/tigris/helm/tool/IdentityVerificationService.html">implementation</a>.</p>

    <h3><a name="access"></a>Access Control</h3>

    <p>Helm's access control system is both the most flexible and the
    most complex part of the system.  <a
    href="/docs/permissions.html">The permission system</a> has a
    user/role/nested group architecture, which effectively restricts
    the actions of users by granting them roles in projects.

    <p>For an integrated tool to provide permission-controlled
    functionality to each of an installation's projects, it must
    either have some internal notion corresponding to Helm's projects
    (as Scarab does), or a separate application data store must be set
    up for each project via a callback (as is done with CVS and
    Issuezilla).</p>

    <p>You can make permission calls using Helm's
    <code>permission</code> <a href="services_xmlrpc.html">XML-RPC
    handler</a>.

    <h3><a name="shared"></a>Shared Objects (1.2)</h3>

    <p>In addition to doing access control, you can obtain information
    about Helm objects via XML-RPC. An integrated tool should obtain
    all of its project and user account information from Helm. This
    may require storing such information in the application's internal
    format (for instance, if there are special application-specific
    users which do not have Helm accounts), which is fine so long as
    changes to the Helm data are always reflected in the
    application.</p>

    <p>You can get user account information using Helm's
    <code>user</code> <a href="services_xmlrpc.html">XML-RPC
    handler</a>.  Other handlers will be forthcoming.

    <p>If you are willing to make your application depend on Helm, you
    can have it compile against the Helm JAR and use Helm objects
    natively (Nidaba does this). Scarab will use Helm objects natively
    but will also be able to run separately from Helm, though I don't
    know how the Scarab team plans to manage this.

    <h3><a name="callbacks"></a>Event-Triggered Callbacks (1.3)</h3>

    <p><i>Note: this is not implemented yet.</i></p>

    <p>Every non-Helm component interfaces to Helm through a
    subclass of the <code>HelmListener</code> class. Each
    implemented method of a registered <code>HelmListener</code> is
    called when the appropriate Helm event happens; for instance,
    <code>projectDeleted</code> is called after the Helm deletion of a
    project. Any given interface probably needs at least a
    <code>projectAdded</code> and a <code>projectDeleted</code>
    implementation so that the resources for a project can be
    initialized and destroyed.

    <p>To register your <code>HelmListener</code> subclass with the
    event handler, you need to put its fully-qualified classname into
    an <code>eventlisteners</code> file. (How?)

    <h2>Conclusion</h2>

    <p>Hopefully by now you have an idea of how to best integrate your
    system with the Helm API system.  If you write new hooks or feel
    that hooks are missing from this document, please feel free to
    email me.</p>
  </body>
d676 2
a677 1
</html>
@


1.7
log
@* Corrected leonardr's email.
* Removed extraneous text for links.
@
text
@d14 1
a14 1
    <small>$Id: integration.html,v 1.6 2001/08/02 22:10:15 dlr Exp $</small>
d52 8
a59 5
    servlet.  Though it is possible to plug in other authentication
    mechanisms (i.e. X.509 certs), the hook to facilitate this process
    has not yet been clearly defined.  The existing hook for external
    authentication mechanisms is a Helm-specific <a
    href="http://jakarta.apache.org/turbine/">Turbine</a> service
@


1.6
log
@Changed document heading to match title.
@
text
@d6 1
d12 1
a12 1
    Leonard Richardson &lt;dlr at collab dot net&gt;<br>
d14 1
a14 1
    <small>$Id: integration.html,v 1.5 2001/08/02 22:07:44 dlr Exp $</small>
d76 2
a77 3
    <code>permission</code> XML-RPC handler.  (<a
    href="services_xmlrpc.html"><i>Information on the Helm XML-RPC
    handlers</i></a>)
d91 2
a92 3
    <code>user</code> XML-RPC handler.  (<a
    href="services_xmlrpc.html"><i>Information on the Helm XML-RPC
    handlers</i></a>) Other handlers will be forthcoming.
@


1.5
log
@Corrected bad HTML for list item.
@
text
@d9 1
a9 1
    <h1>Integration HOWTO</h1>
d13 1
a13 1
    <small>$Id: integration.html,v 1.4 2001/07/31 23:04:28 leonardr Exp $</small>
@


1.4
log
@Updated with information about permission checking, shared objects, and callbacks.
@
text
@d13 1
a13 1
    <small>$Id: integration-HOWTO.html,v 1.3 2001/07/24 23:18:33 dlr Exp $</small>
d37 1
a37 1
	<li><a href="#access">Access Control</a></li
@


1.3
log
@* Enhanced Overview.

* Fleshed out Authentication and ACL sections, and made breif notes in
Callback Registration and Event Notification sections.
@
text
@d11 3
a13 2
    July 24, 2001<br>
    <small>$Id: integration-HOWTO.html,v 1.2 2001/07/24 22:54:36 dlr Exp $</small>
d37 3
a39 3
	<li><a href="#acl">Access Control Lists (ACL)</a></li>
	<li><a href="#callbacks">Callback Registration</a></li>
	<li><a href="#events">Event Notification</a></li>
d44 3
a46 2
    <h3><a name="auth"></a>
      <a href="/apidocs/org/tigris/helm/security/">Authentication</a></h3>
d48 70
a117 30
      occurs through login via a web-based UI.  The code which
      currently handles this activity is the
      <a href="/apidocs/org/tigris/helm/domain/TLogin.html">TLogin</a>
      servlet.  Though it is possible to plug in other authentication
      mechanisms (i.e. X.509 certs), the hook to facilitate this
      process has not yet been clearly defined.  The existing hook for
      external authentication mechanisms is a Helm-specific
      <a href="http://jakarta.apache.org/turbine/">Turbine</a> service
      interface 
      <a href="/apidocs/org/tigris/helm/tool/IdentityVerificationService.html">implementation</a>.</p>

    <h3><a name="acl"></a>
      <a href="/apidocs/org/tigris/helm/security/AccessControlList.html">ACL</a></h3>
    <p>Helm's ACL system is both the most flexible and the most
      complex part of the system.
      <a href="/docs/permissions.html">The ACL system</a> is the
      implementation of a user/role/nested group architecture, which
      effectively restricts the actions of users by granting them
      roles in projects.  Since projects may contain sub-projects, </p>

    <h3><a name="callbacks"></a>
      <a href="/apidocs/org/tigris/helm/security/PluginService.html">Callback Registration</a></h3>
    <p>Still being defined.  Currently supported include single-JVM
      Java bytecode level callbacks, and
      <a href="http://xml-rpc.com/">XML-RPC</a> calls.</p>

    <h3><a name="events"></a>
      <a href="/apidocs/org/tigris/helm/security/PluginService.html">Event Notification</a></h3>
    <p>Still being defined.  Currently supported include single-JVM
      Java bytecode level event notification.</p>
d120 1
d122 3
a124 3
      system with the Helm API system.  If you write new hooks or feel
      that hooks are missing from this document, please feel free to
      email me.</p>
@


1.2
log
@Fleshed out overview a bit.
@
text
@d12 1
a12 1
    <small>$Id: integration-HOWTO.html,v 1.1 2001/07/24 22:27:41 dlr Exp $</small>
d17 3
a19 3
      of systems taking advantage of this API include
      <a href="http://issuezilla.tigris.org/">IssueZilla</a> and
      <a href="http://scarab.tigris.org/">Scarab</a> (coming
d45 11
a55 1
    <p></p>
d59 6
a64 2
    <p>Helm's ACL system is the most both the most flexible and
      complex part of the system.</p>
d68 3
a70 1
    <p></p>
d74 2
a75 1
    <p></p>
@


1.1
log
@Seedling of the systems integration guide to the Helm API.
@
text
@d12 1
a12 1
    <small>$Id: component-HOWTO.html,v 1.9 2001/03/26 21:39:46 dlr Exp $</small>
d35 4
a38 4
	<li>Authentication</li>
	<li>Access Control Lists (ACL)</li>
	<li>Callback Registration</li>
	<li>Event Notification</li>
d43 2
a44 1
    <h3>Authentication</h3>
d47 4
a50 2
    <h3>ACL</h3>
    <p></p>
d52 2
a53 1
    <h3>Callback Registration</h3>
d56 2
a57 1
    <h3>Event Notification</h3>
@

