head	1.4;
access;
symbols
	TIGRIS_1_1_0RC2:1.4
	TIGRIS_1_1_0RC1:1.4
	TIGRIS_1_1:1.4.0.4
	TIGRIS_1_0_8:1.4
	TIGRIS_1_0_8RC3:1.4
	TIGRIS_1_0_8RC2:1.4
	TIGRIS_1_0_8RC1:1.4
	TIGRIS_1_0_7:1.4
	TIGRIS_1_0_7RC3:1.4
	TIGRIS_1_0_7RC2:1.4
	TIGRIS_1_0_7RC1:1.4
	TIGRIS_1_0_6:1.4
	TIGRIS_1_0_6RC5:1.4
	TIGRIS_1_0_6RC4:1.4
	TIGRIS_1_0_6RC3:1.4
	TIGRIS_1_0_6RC2:1.4
	TIGRIS_1_0_6RC1:1.4
	TIGRIS_1_0_5:1.4
	TIGRIS_1_0_5RC6:1.4
	TIGRIS_1_0_5RC5:1.4
	TIGRIS_1_0_5RC4:1.4
	TIGRIS_1_0_5RC3:1.4
	TIGRIS_1_0_5RC2:1.4
	TIGRIS_1_0_5RC1:1.4
	TIGRIS_1_0_4:1.4
	TIGRIS_1_0_3:1.4
	TIGRIS_1_0_2:1.4
	TIGRIS_1_0_1:1.4
	TIGRIS_1_0:1.4.0.6
	TIGRIS_1_0_0:1.4
	TIGRIS_1_0_0_RC1:1.4.0.2;
locks; strict;
comment	@# @;


1.4
date	2001.03.20.21.53.32;	author brian;	state Exp;
branches;
next	1.3;

1.3
date	2001.03.09.19.24.08;	author leonardr;	state Exp;
branches;
next	1.2;

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

1.1
date	2001.02.22.02.52.25;	author leonardr;	state Exp;
branches;
next	;


desc
@@


1.4
log
@
Obtained from:
Submitted by:
Reviewed by:

We're now doing the right thing.  And, fix a centering problem.
@
text
@<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
  <head>
    <title>The Helm Peer Port and You</title>
  </head>

  <body>
    <h1>The Helm Peer Port and You</h1>
    Leonard Richardson &lt;leonardr at collab dot net&gt;<br>
    February 22, 2001<br>
    <small>$Id: peerport.html,v 1.3 2001/03/09 19:24:08 leonardr Exp $</small>

<h2>Introduction:</h2>

<p>Around January 20th, 2001, Daniel Rall and I discovered a serious
flaw in the Helm architecture. Ever since the implementation in Helm
of a business object architecture, each business object has been
retaining the Connection object which spawned it. The problem with
this is that when a particular business object outlives its
Connection, then system errors (seemingly emenating from the database
driver) will start to occur.

<p>This flaw managed to go unnoticed for quite a while because it was
only recently that we started caching business objects on a large
scale, greatly extending the lifetime of business objects. 

<p>If you are running Helm and start experiencing this problem, the
officially reccommended workaround is to restart the server when
problems start occuring. It's unlikely that this problem will actually
corrupt your data, but it is extremely annoying.

<p>On February 20, 2001, we merged what had formerly been a branch
(the HELM_PEER_PORT_BRANCH) into the HEAD of the tree. The default
version checked out of CVS now uses Turbine's Peer system instead of
Joist's TableManager system (however, Joist is still a requirement for
building Helm, because it uses some of Joist's utility classes).

<h2>The New Architecture:</h2>

<p>After some false starts, Daniel and I decided to rearchitect Helm
to use Turbine's Peer system. Since this required a complete port of
all the Helm code, we figured we might as well make some other, less
significant architectural changes while we were at it. We also took
the opportunity to consistently apply architectural guidelines and
tools developed while building the old system.

<p>However, the main change made in the new system is the move to
Turbine Peers. Peers are approximately equivalent to Joist
TableManagers. The cool thing about Peers is that they are generated
from an XML description of the database using the Turbine tool called
<a href="http://java.apache.org/turbine/torque/">Torque</a>. 
The generated peers and business objects are not in CVS at all;
they are generated with a Torque call as part of the
build. 

<p>Should we add a new table to the database, we don't have to write a
new Peer; we just describe the new table in helm-schema.xml, rerun
Torque, and watch as a Peer and a business object are generated.

<div align="center">
<table border=1>
<tr>
<td>
<pre>
BaseFooPeer (Generated)     BaseFoo (Generated)
    ^                          ^     
    |                          |
 FooPeer                      Foo
</pre>
</td>
</tr>
</div>

<tr>
 <td>
  Figure 1: Class hierarchy for the Peer and business object representing the
  HELM_FOO table. 
 </td>
</tr>

</table></div>

<p>From a description of the HELM_FOO table, Torque generates
BaseFooPeer and BaseFoo. BaseFooPeer implements almost all neccessary
interaction with the database, and BaseFoo implements get and set
methods for each field in the HELM_FOO table. FooPeer and Foo are for
user additions later on. In the Foo class we implement every method
needed by templates or servlets.

<p>All interaction with the Peer is handled through Turbine Criteria
objects. Criteria objects are like the Joist Criterion objects, but
more featureful. Our full adoption of Criteria objects allows us to do
away altogether with the shameful practice of hard-coding SQL
statements in Java code.

<p>We should never have to use a Connection object again (we might,
but I can't think of a specific example where we'd need one). The
Peers take care of all connection handling for us. This means that
this major rearchitecturing should actually solve our problem. :)

<h2>Contributions back to Turbine</h2>

<p>The Torque tool, the Peer class, and the Criteria class have all
been improved as a direct result of feedback from the Helm porting
team. Our struggles have benefited the Open Source community at large,
even that portion of it which will never use Helm. Kudos to John
McNally and Daniel Rall for implementing the changes and buxfixes we
needed.

<h2>Less Earth-Shaking Changes</h2>

<p>These are some of the changes we made from minor redesigns and
consistent application of old redesigns. All of these should make your
life easier.

<ul>

<li><b>Tasking:</b> The Helm task system has undergone a major
redesign, though it's still not the greatest design in the world. One
excellent features is that the TigrisUpdate class has finally been put
to rest, its methods appropriated into HelmTask. As with all the other
redesigns, we've ported all instances of the old system to the new
system, so when in doubt, look at examples.

<li><b>Audit Log:</b> Helm had an audit log before, but it logged
relatively few actions. The new log logs many more actions.

<li><b>System-Generated Email:</b> All places where the system sends
email should be handled using HelmEmailer (or Emailer if email is
being sent to someone who's not a user on the system) and
TurbineWebMacroService (which, incidentally, replaces Helm's old
TemplateInterpolator). This means that system-generated email messages
can be customized without changing Java code.

<li><b>Pagination:</b> Pagination is much, much easier than
before. It's no longer neccessary to have a
PaginatableDatabaseBackedList subclass for every type of business
object you want paginated. Instead, you merely use PDBL-alike
PeerBackedList, which can paginate anything. Business-object-specific
information, such as the list of fields which are important to filter,
goes into the appropriate Peer where they belong. The practical upshot
of this is that many more List-returning methods return
PeerBackedLists. There are wrapper methods avaliable for all such
methods, if you don't want the template to paginate. <a
href="/docs/pagination-HOWTO.html">The pagination HOWTO</a> will be
updated soon to describe the new system.

</ul>

<h2>Guidelines for working on the new port:</h2>

<p>All the changes we made should be invisible to the end user. Our ideal
is to have the new system work exactly like the old system, but to
suck less. To the servlet author, and, to a much lesser extent, the
template author, our changes are not invisible. Here are some
guidelines to keep in mind when working on the new system.

<ul>

<li><b>Access Control API Simplified:</b> Access control is now
handled via objects instead of IDs. You no longer call
acl.hasPermissionForProject(action, projectID). Instead, you call
acl.hasPermission(action, project).

<li><b>API Simplified:</b> In general, methods which used to
take IDs now take objects. Our experience has been that the calling
method invariably has the object anyway, and there's no need to pass
only the ID when the method accepting the ID is probably going to just
reconstruct the object.

<li><b>Backwards Compatible, Mostly:</b> Templates do not need to be
rewritten. However, each one does need to be checked for changed
method calls (we have done this for all non-instantiation-specific
templates, and for the tigristinst instantiation templates). In
particular, the calls to access control methods (see above) need to be
changed. The latter can be done automatically with Perl
search-and-replace. Also, you may want to rewrite templates to take
advantage of new methods which return paginatable lists.

</ul>

<h2>Testing:</h2>

<p>We have a very thorough test plan which the CollabNet folks are
using to QA the new HEAD. Jason Robbins is currently working on the
test plan, and will soon be putting it on Tigris.org, at which point
it will be linked from (at least) here.

<p>We will be going through the test plan several times; once as host
admin to ensure that everything works as it should, then several times
more as users with decreasing permissions so as to ensure that the
permission checking has been ported correctly.

<p>Suggested additions to the test plan are welcomed, and should be
sent directly to the bad boy of quality assurance, Mike Sussman
(msussman at collab dot net). If you want to find embarassing bugs not
covered by the test plan, your best bet is to create new roles with
funky permissions and see what users with those roles can do.

<h2>Thanks:</h2>

<p>In addition to Daniel and myself, Elicia David, Jody Edmondson, and
Ed Korthof put in a lot of work on the port. John McNally and Jon
Stevens deserve kudos as well for their help with and patches to
Turbine.

</body>
</html>@


1.3
log
@Made the format like the format of my other docs.
@
text
@d11 1
a11 1
    <small>$Id: peerport.html,v 1.8 2001/02/21 01:56:43 leonardr Exp $</small>
d51 4
a54 6
<a
href="http://java.apache.org/turbine/torque/">Torque</a>. <i>(Ideally,
the generated peers and business objects should not be in CVS at all;
they should be generated with a Torque call as part of the
build. However, at the moment they are stored in CVS, in the
<a href="/source/browse/helm/java/org/tigris/helm/om/base/">.org.tigris.helm.om.base</a> package.)</i>
d81 1
a81 1
</table>
@


1.2
log
@Corrected typo.
@
text
@d1 11
a11 2
<h1>The Helm Peer Port and You</h1>
<h3>by Leonard Richardson</h3>
d208 3
@


1.1
log
@Added news about the port and a document describing the changes we made.
@
text
@d197 1
a197 1
Stevens deserve kudos as well for his help with and patches to
@

