Grouper Developers Forum

[Tom Barton <>]

Putting this thread on the grouper-dev list to gain further input. -Tom

--- Begin Message ---

• From: Tom Barton <>
• To: Chris Hyzer <>
• Cc: Shilen Patel <>, Tom Zeller <>, "GW Brown, Information Systems and Computing" <>
• Subject: Re: GSH
• Date: Tue, 17 Mar 2009 09:18:49 -0500

Thanks Shilen for bringing this up.

I agree there's a balance to be struck, and I think we're close to it with gsh (close enough, anyway). The balance is first of all over what operations to wrap-up in a gsh class. I can give a rationale for what to pick, and that's "lightweight-but-good group management". Think EZgrouper. I think we're tolerably close to that in gws as well. In fact, how closely aligned are gsh and gws, when you only count gsh's gsh-specific methods?

Tom

Chris Hyzer wrote:

1. First of all, how are we determining if something should be added
to GSH? In my view, something is added to GSH if help() says
something about it regardless of if all it's doing is calling the API
directly.

Right, but anyone can call any public java method with GSH, right? You mean what we
"document / support" in GSH?

On the one hand, we probably don't want to add every public method in
the API to GSH because that would get overwhelming for the user. But
also, having nothing would also make it difficult for the user to
perform common tasks (add group, add user, etc...).

So for instance, not to pick on old decisions, but GSH has a help item
for GrouperReport.report(). All that does is call the API directly.
So is it in the help because we think enough users would be interested
in that call and not having it would make too many people either
unaware of the feature or cause them difficulties to look in the API
to find how to use the feature?

Right. We should document things in the help to make them apparent / easy to
do.

2. Also, I'm seeing some inconsistencies in GSH. For instance, we
have the following:

addMember(group, subject id)
member.changeSubject(newSubject);

Note that the first uses a GSH class while the second calls the API
directly. And "subject id" in the first is a String while
"newSubject" in the second is a Subject. So why didn't we use the API
in both cases?

group.addMember(Subject)
member.changeSubject(newSubject);


Or use separate GSH classes in both cases?

addMember(group, subject id)
changeSubject(member, subject id);


The main reason why I'm asking these questions is just to know how we
want to do things moving forward.

Thanks!

-- Shilen

Well, I think an addMember is something that is frequent to do, can be done
without a lot of params, so we can make that easy. Also, it existed before I
got here. :) Member change subject isn't frequent, and it was complicated to
put in GSH when I was implementing it. I started out doing the latter, but I
thought it was confusing for the user to have:
changeSubject(oldSubjectSource, oldSubjectId, newSubjectSource,
newSubjectId), when typing in GSH it got confusing what went where... whereas
member.changeSubject(subject) looked more straightforward just to leave as
is.

I think when a method is heavily overloaded, it is not a good idea to expose
a big method in GSH, because people will want more/different overloads, there
is no intellisense (auto typing that eclipse gives you) so its hard to type
it in, so method chaining is good. And if its like your copy or move method
that has method chaining in the API, then lets just document it and we are
done.

In summary, except for simple heavily used operations, I think we should err
on the side of documenting the API in the GSH help files (website and help
text in GSH)... How many places can we expose the API differently to the
user? (API, WS, client, GSH, etc?) :)

Sound good?

Thanks,
Chris

--- End Message ---