aspose file tools*
The moose likes Beginning Java and the fly likes Documenting JavaBeans Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "Documenting JavaBeans" Watch "Documenting JavaBeans" New topic
Author

Documenting JavaBeans

Linda Thomas
Ranch Hand

Joined: Jun 21, 2004
Posts: 36
I am due to leave my position here as a student web developer and I want to leave documentation on one particularly large and complex program I coded that will assist future students who may need to modify the code.

It is the only program that uses JavaBeans (long story) and this could be very confusing for any student who has to work with the code.

Basically I used JavaBeans to create 4 objects: clients, counsellors, visits and users (logged in). The program gets confusing because when I would have a client form and use the clientbean created from information retrieved from the database when the user would click next to display a verify page (displaying the information they inputted/updated) the clientbean would be updated (since the form objects were named after clientbean properties). If the user backed out at this point, by say using the Back button on IE's toolbar (which I wouldn't be able to tell), then the data in clientbean would be corrupted.

I solved this by using tempclientbean (only where forms were concerned). Same thing for counsellors, visits, user (if they needed to change some of their own information) so I now had userbean, clientbean, counsellorbean, visitbean as well as tempuserbean, tempclientbean, tempcounsellorbean, and tempvisitbean. That added up to a lot of beans.

<< If anyone wants to point out here another way I could have handled this or point me to a link for future reference I would appreciate it. >>

So my problem is documenting my beans in a way that people looking at my code would know what the heck I did (sometimes I wonder myself, lol). I tried with Visio and a modified version of my Navigation diagram but it got messy fast. Should I use the Navigation diagram but only put the main bean and its temp? The Navigation diagram got to be a bit big considering the scope of the project.

What about a flowchart? I have commented my code but I still think that they will need more to be able to cope with the program. Its not a bad program, the use of beans has let me ignore the countless functions needed to replace special characters and other functions needed to modify information passed between pages and the database. Its just that no one else here is learning how to use beans and that will be the issue if the program needs updating. Even the Web Master doesn't understand or know how to use JavaBeans.

[ December 19, 2005: Message edited by: Linda Thomas ]
[ December 19, 2005: Message edited by: Linda Thomas ]
Scott Selikoff
Saloon Keeper

Joined: Oct 23, 2005
Posts: 3704
    
    5

Are you familiar with JavaDoc? Its a pretty good way to document the methods in each class, although does not generally help for ER models.


My Blog: Down Home Country Coding with Scott Selikoff
Linda Thomas
Ranch Hand

Joined: Jun 21, 2004
Posts: 36
Yup I've worked with JavaDoc. It's great for complex classes, such as the class files we use to access stored procedures, but I'm thinking of something to help them with the JSP pages.

They are used to getting information on each page with an Object[]. Now I thought that this was pretty wasteful considering the amount of information I was retrieving and that the user would generally work with one client at a time. Every Object[] is a retrieval of a call to the database for information.

Example:
Old Way
1. Search Client (input whatever data you wanted to search by)
2. Use Object[] to display search results, a list of clients matching inputted data.
3. Click on a client (names are hyperlinks with Client Number).
4. Display general information regarding a client (because there is too much info). Use Object[] to get Name, Client Number, Date of Birth, etc.
5. Click on link, ie. Personal Information.
6. Use Object[] to display Client's personal information.
7. Click Update button to change some personal information.
8. Use Object[] to grab Client information and insert into form (form is 2 pages long so only half of Client information is used but all is retrieved so only one stored procedure is needed instead of two).
9. Update necessary information and click Next.
10. Use Object[] to grab rest of Client information to insert into second page of form. Grab information from previous page and save as variables.
11. Update necessary information and click Next.
12. Display Verify Page. It grabs information from previous page's form objects as well as the variables passed from the first form and displays for the user to confirm.
13. Java class grabs all information from Verify Page from variables passed as hidden input objects.

My JavaBean Way
1. Search Client (input whatever data you wanted to search by)
2. Use Object[] to display search results, a list of clients matching inputted data.
3. Click on a client (names are hyperlinks with Client Number).
4. Pass Object[] to clienbean and fill in all properties. Display general information regarding a client using clientbean Get methods.
5. Click on link, ie. Personal Information.
6. Display Client's personal information using clientbean Get methods.
7. Click Update button to change some personal information.
8. Create tempclientbean and use Set methods to insert clientbean information that won't change (ie. Client Number). Name form objects to match tempclientbean properties and set value using clientbean Get methods.
9. Update necessary information and click Next.
10. Name form objects to match tempclientbean properties and set value using clientbean Get methods.
11. Update necessary information and click Next.
12. Display Verify Page. Display Client Information using tempclientbean Get methods.
13. Java class grabs all information using clientbean Get methods.

Using tempclientbean as the form objects but clientbean as the values allows the user to change information and move forward without corrupting clienbean. But if they click the back button and hit the refresh button the form would be repopulated with clientbean information as it is the value of the form objects.

Hope that makes sense. Basically we grab information and if we need it across multiple pages we use the URL or hidden input fields. If we use URL's we need to use functions to modify the data passed otherwise spaces are replaced with %20 (or something similar). Then on the receiving page we need another function to revert it back to something we can display. So some information is passed across mutliple pages, sometimes not being used on any of those pages until the final confirmation page just so we can recreate a page generated with a call to a stored procedure (a way of remembering the user's original choices that got them the list 5 pages back).

[ December 19, 2005: Message edited by: Linda Thomas ]

[ December 19, 2005: Message edited by: Linda Thomas ]
[ December 19, 2005: Message edited by: Linda Thomas ]
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Documenting JavaBeans