Geert Bevin wrote:
Also, since three years, no public APIs get committed anymore without
Javadocs. Additionally, as you probably saw, each release contains
extremely detailed release notes with examples that are afterwards
aggregated in the wiki's cookbook. I think that there is no
open-source project out there that does this as extensively. Stating
that documentation is an afterthought thus feels really very harsh to me.
I'm glad to hear the first part of that, and yes, I did notice a lot of
examples in the release notes, which are great. My harsh comment was
based solely on the parts of the framework I've tried to use. The
template system is quite well documented, enough so that I felt
confident editing the Wiki to clarify the one thing I found I had to ask
on the list about. And the simple blog movie, as I mentioned, is a very
good introduction. It was therefore pretty jarring that the first thing
I tried to do after finishing the tutorial (add database authentication)
was essentially undocumented. As was the thing I tried to do after that
(get rid of the URL decoration). And the thing after that (beefing up my
model with some more complex database access).
It is entirely possible that I just happened to hit the worst-documented
three parts of the framework all in a row.
A project with the momentum of Spring, with their amount of
contributors and commercial companies behind it, is of course able to
provide a lot more in terms of books and user guides. There's only so
much that a small team of motivated developers can do for free in
their spare time. However, if you do feel that some areas need to be
improved quicker, you're always welcome to contribute to the effort
and document your findings either in articles or Javadoc additions
that you can send to me as patches.
I am happy to update the documenation in places where I feel like I have
a solid enough understanding of the subject to make a useful
contribution. And FYI, my comment about Spring was more about the
Javadoc than the books and user guides (though those are nice too).
Sounds like you have that problem under control for new code, but as a
new RIFE user I have no way of knowing in advance what code is new and
what code is old, so from my perspective the documentation is a random
roll of the dice: will there or won't there be any documentation for
what I want to do?
I'm working on a series of three short books for O'Reilly though, so
soon there will be a source with more centralized information.
Looking forward to those!
You're right that database authentication isn't documented in detail
and it really needs to receive some love since imho it's *the* area
that is the most confusing to people. I think that you can find what
you need here though:
http://thread.gmane.org/gmane.comp.java.rife.user/2767/focus=2767
I read that thread when it came by. It does not answer a single one of
the questions I posed in my blog post. Which I'll repeat here with some
clarifications so people don't have to go over there:
What table does the authentication system use for user data, and what
are its columns? (In development mode, it's fine to have the framework
auto-create tables. Not so in production; I want to control exactly
where and how each table is created, make sure I understand all the
integrity constraints, have administrative tools in place to manipulate
the data in a safe way, etc.)
How does one add or remove a user? (The XML user data gets cached in
memory, so if I just update or insert a database row in the users table,
do I need to notify a cache manager? Is there a way to disable a user
without deleting the row entirely?)
Does the user table have to be completely managed by the authentication
system -- no touching it allowed -- or can it be a user-supplied table
that has data other than login names and passwords? If so, how does one
tell the code to use the alternate table, and how does one get at the
additional data?
Is it possible to store session data somewhere other than a database,
e.g. in a clustered cache?
Other posts on the mailing list cover this too. You don't really have
to be following the list for a long time, since a simple search should
reveal all the posts that are relevant to you.
I did search and I did not find the answers to my (relatively common, I
believe) questions. But I guess a larger point is that if I have to
search a mailing list archive on a regular basis, it's a sign of an
inadequately-documented system. A mailing list is a very inefficient
reference book -- even if what you want is there, you have to dig
through a lot of noise to get an answer, especially if it's something
that might match a variety of different sets of keywords.
I will pledge to do my part on this and update the Wiki with any answers
I get from the list. I suppose if everyone, or even most people, did
that, the need to search the mailing list would be much less.
One of the points of the query builders is that the order is not fixed
at all. The real statements are only created when the SQL is obtained
from the builder manually, or when it's executed. This also means that
you can partial query builder objects that you prepare in one location
of your code and complete elsewhere.
Great, that helps. Thanks. I have updated the "Generic query manager"
Wiki page with that information and a couple examples of specifying
multiple query conditions. Hopefully they're accurate; I'm kind of
guessing at how the "whereAnd" method works. (My guess: it acts as a
"where" if it's the first condition, or an "and" if it's not.)
I'd like to include an example of mixing "field()" and "where()" but I'm
not really sure what field() does in the context of a restore query,
whose fields are presumably already tied to the members of a particular
class. So I guess that's another question: what is RestoreQuery.field() for?
I hope this information lets you climb out of the dip you're in and
get back up to speed. Otherwise, feel free to mail the list with any
additional questions you have, you'll see that a lot of people here
are very helpful.
Indeed, it's the fact that I've seen most questions answered helpfully
that's one of the most attractive things about RIFE.
Thanks for the reply!
-Steve
_______________________________________________
Rife-users mailing list
[email protected]
http://lists.uwyn.com/mailman/listinfo/rife-users
