Meaningless Drivel is fun!*
The moose likes JSP and the fly likes Best way to document EL values in *Scope variables Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » JSP
Bookmark "Best way to document EL values in *Scope variables" Watch "Best way to document EL values in *Scope variables" New topic
Author

Best way to document EL values in *Scope variables

Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

It not clear to me how to best document what values are set by the beans/servlets into the sessionScope, requestScope. applicationScope or pageScope.

Assume that all the beans and servlets have wonderful Javadocs. So in theory, the UI designer can read the Javadocs and see that once they have a value from the fooScope, they know what they can do with it, what "properties" they can call from Javascript or EL, etc.

But I'm not seeing an obvious way to tell them what values are stored in the fooScope, to begin the process of accessing members and functions.
Bear Bibeault
Author and ninkuma
Marshal

Joined: Jan 10, 2002
Posts: 60774
    
  65

Well, you could always include a comment at the beginning of the JSP outlining the contract that must be met in order to use it.

But, as we know, comments have a way of getting out of date, so I augment any comments I place in a JSP with a custom "contract" tag that actually verifies that the contract has been met.

Some real-world examples from one of my JSP pages (the one that implements the About Box view):

("affinity" is the project name of the proprietary framework I've set up for our application).

The type attribute is optional.

The tag checks that the scoped variable exists if required, and optionally its type. If the contract is broken, a (proprietary) ContractBrokenException is thrown.

This tag not only flushes out regression bugs where the contract might be broken by a change, but also serves as the contract documentation.


[Asking smart questions] [Bear's FrontMan] [About Bear] [Books by Bear]
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

Hmm, that's interesting; COP (tm... *sigh*) for JSP. Do you pull out documentation by simplistic JSP parsing?
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

Bear Bibeault wrote:Well, you could always include a comment at the beginning of the JSP outlining the contract that must be met in order to use it.

Interesting approach. But its addressing the wrong end of what I am concerned with. It says "JSP, expect these..." and I was looking for something that would tell the JSP author, earlier in the process:

You have access to these things for your EL.

Bear Bibeault
Author and ninkuma
Marshal

Joined: Jan 10, 2002
Posts: 60774
    
  65

Pat Farrell wrote:
Interesting approach. But its addressing the wrong end of what I am concerned with.

Then I would say that you are approaching the issue from the wrong direction. The controller should be meeting the needs of the JSP rather than forcing the JSP to contort itself around whatever the controller decides to send it.

The JSP defines the contract; it's the controller's job to meet that contract.
Bear Bibeault
Author and ninkuma
Marshal

Joined: Jan 10, 2002
Posts: 60774
    
  65

David Newton wrote:Do you pull out documentation by simplistic JSP parsing?

No, I've never found a need to do that.

Anyone writing a controller that will forward to the JSP looks in the JSP for the contract.
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

Bear Bibeault wrote:The JSP defines the contract; it's the controller's job to meet that contract.


Perhaps technically, but that is not how I see real world development. The GUI guy is told to make it pretty, invents nice looks and tries to implement it. Then the GUI guy want to add a cool widget. How does he learn that is already there, and just needs to know how to use it, and how does he know that he needs to make an RFE to the engineers in charge of the beans?
Bear Bibeault
Author and ninkuma
Marshal

Joined: Jan 10, 2002
Posts: 60774
    
  65

Your real-world development differs from any real-world environment I've ever worked in.

Also, "widgetry" is different from scoped variables. Most widgetry is client-side. Are your designers not client-savvy?
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

Extend the question a bit. The Bean guy puts cool stuff in scoped variables. How does he document which stuff is in which scope? I hate that variables often start as requestScope, adn get moved to sessionScope in the bean, and it breaks all the JSP pages.

Similar quesiton the other way, how does the bean document what fields it expects from form posts? In the olden days, we had getters and setters for properties, and it was obvious. Now we do it implicitly, calling getQueryParamter("Foo") so how does the page author know that foo is accptable but baz is not?
Bear Bibeault
Author and ninkuma
Marshal

Joined: Jan 10, 2002
Posts: 60774
    
  65

Pat Farrell wrote:Extend the question a bit. The Bean guy puts cool stuff in scoped variables. How does he document which stuff is in which scope?

Again, I don't think it's the "bean guy's" job to put anything in scoped variable that the JSP doesn't ask for. For me, the JSP is "the boss". It dictates what it needs to do its job, and the controller falls all over itself to supply it.

This ensures that the JSPs are as clean and as simple as possible. Otherwise, if the JSP needs to adapt itself to whatever the "bean guy" decides it wants to send to the JSP, the JSP ends up with all kinds of unnecessary goop that is needless.

The needs of the JSP should drive the development of the controllers. Not the other way around.

I hate that variables often start as requestScope, adn get moved to sessionScope in the bean, and it breaks all the JSP pages.

Huh? There's nothing that automatically makes this happen. Or are you talking about the "bean guy" being a dumb ass and changing things without taking the needs of the JSP into account? See above. The "bean guy" should be a service to the JSP, not the other way around.

Similar quesiton the other way, how does the bean document what fields it expects from form posts? In the olden days, we had getters and setters for properties

Ummm, we still do. All my submissions are bean-based, with getters/setters that match the submitted request parameters. These so-called "form beans" serve as the "list" of expected values.

Now we do it implicitly, calling getQueryParamter("Foo")

Who is "we" here? it's certainly not me.
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

I think the bear is being a bit bear like. Back off a bit from the literal question.

There are lots of dumb-ass programmers out there. The bean guy gets a RFE that the foo is not working as a requestScope, can you make it a sessionScope, and he does and one JSP is happy, and a bunch break.

There seems to be no standard documentation for either what the bean publishes, and what the JSP subscribes to.

In a couple of years, all the guys have been replaced by gals, and they want to read the documentation to know where to grok this. Where do they look?

The bean guy put stuff in the fooScope for some JSP that was written long ago in a galaxy far away, who remembers this stuff?

While the "JSP can drive the bean" development, after a while there exists a bunch of bean code that works, is tested, and in production. A new JSP is needed. how do you start?
Bear Bibeault
Author and ninkuma
Marshal

Joined: Jan 10, 2002
Posts: 60774
    
  65

No growling here; just strong opinions (as per usual).

New JSPs == new contracts. Any other mode of development for web applications is, in my opinion, inherently broken. Is this an actual environment in which you are working? Are you able to institute changes in the process?

To me, it is a setup for failure to write new JSPs that are expected to mold themselves to existing (hostile?) controllers, rather than to create controllers specifically geared towards serving the needs of the JSP.

To further address the original question, I can think of no amount or mode of documentation that can fix a process where the needs of the JSP are pushed aside in favor of whatever the controllers want to do in a vacuum. Perhaps the best that can be done in such an situation is to carefully Javadoc the environment that the controller sets up so that the hapless JSP developer has someplace to look for what is made available by that controller.
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

Bear, you are really missing the point here. Perhaps your strongly held opinions are blinding you.

Of course I can change the environment. But I can't ensure perfect human to human communication.

Sometimes its a new JSP, sometimes its a mod to an existing one.

But there has to be some way to describe what the controller is doing today, so you can start thinking about what RFE to make to improve it.
Your approach describes what the JSP is expecting today, but nothing about what it expects tomorrow. And we know that the PHB will ask the JSP developer to change it tomorrow.

I'm trying to avoid having the JPS and Bean developers needing to do a mind meld each time something needs to be changed.
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

I don't see how that's possible; if they're not both involved in the RFE/etc. process then *someone's* going to have to communicate their needs and/or expectations and/or capabilities. The JSP person needs to know what's available (for example, if using JSP EL, the scoped beans, and their publicly-accessible getters). If the JSP person needs something else, they have to ask for it.

On the other side, the bean person can't just put everything possible into scope, for all the obvious reasons, but must be able to communicate what *is* available.

So I sort of see that being driven by the JSP person, since resource constraints disallow the bean person putting everything possible into scope. In the past I've driven the documentation by adding simple Javadoc tags (@request, @session, @application) to whatever is sending data to the JSPs. At the same time, I've never had JSP people that couldn't figure out Javadocs.

(I've never had a problem with beans switching scopes, because I almost never explicitly specify bean scope in my EL, and wouldn't really want to.)
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

David Newton wrote:I don't see how that's possible; if they're not both involved in the RFE/etc. process then *someone's* going to have to communicate their needs and/or expectations and/or capabilities. The JSP person needs to know what's available (for example, if using JSP EL, the scoped beans, and their publicly-accessible getters). If the JSP person needs something else, they have to ask for it.


But how is the history recorded? We have Javadocs to record the API. Its served us well for more than a decade. What we don't seem to have is a way to document what is pushed into the EL scope by the bean.


David Newton wrote:(I've never had a problem with beans switching scopes, because I almost never explicitly specify bean scope in my EL, and wouldn't really want to.)


I think I may have been unclear. I'm specifically talking about EL variables that are placed in pageScope, applicationScope, sessionScope, etc.
The bean author scopes the values and the JSP author has to exactly match the scope. If the JSP asks for a requestScope'd variable when its in the sessionScope, they get nothing.
Bear Bibeault
Author and ninkuma
Marshal

Joined: Jan 10, 2002
Posts: 60774
    
  65

Pat Farrell wrote:The bean author scopes the values and the JSP author has to exactly match the scope.

No, they don't.

The expression:will match a scoped variable named whatever in any scope.

I'd pose that it is bug (in the making) to specify: when the scope is moot.
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4646
    
    5

Bear Bibeault wrote:I'd pose that it is bug (in the making) to specify: when the scope is moot.


I had no idea that this is expected. All of the examples explicitly use the scope, I think even the FrontMan documentation.

And yes, I've been bitten by the change of scope a lot. Which is one of the things that motivated my question.
D. Ogranos
Ranch Hand

Joined: Feb 02, 2009
Posts: 214
Yes thats a documented feature of the EL: it looks for variables in the order page scope -> request scope -> session scope -> application scope.

Personally when developing a JSP I like to think of it as a method, having a signature to expect certain parameters. I found that <jsp:useBean ...> helps a bit with this (similar to what Bear does in his example above).

Example:


When I write this at the beginning of the JSP, I see with one look that the page expects a scoped variable "myobject" of type MyBeanClass (you can also provide the scope attribute if you know where the bean will be). If the bean is not available when the page is called, an exception will be thrown and you know what happened.
 
 
subject: Best way to document EL values in *Scope variables
 
Similar Threads
capturing variable in "value" field of the form
Compare between EL and TagLib
JSP Bean,not able to work my first bean
Database problems
Mommy, where do parameters come from?