ClassName |
|
|---|---|
Component |
|
One of the most common operations in an HTML application is listing the results of some database query. In Relational Views terms, this means finding the proper RelationalView or subview, calling select on that RelationalView, and then printing out the resulting array.
Because this happens so often, Relational Views provides a servlet bean named RelationalViewDroplet that takes care of most of the work. This servlet bean allows a .jsp page to specify a RelationalView and subview, execute a query, then pass the results of that query to another servlet bean (such as the ForEach servlet bean) for display. All of this can be done without any Java code.
Input Parameters
rviewName
As demonstrated in the previous example, this parameter specifies the name of the RelationalView to be displayed.
rview
Instead of specifying the name of a RelationalView in rviewName, you can use this parameter to pass the actual RelationalView you want to use. The value of this parameter usually comes from the property of some object, or from some other parameter. The RelationalView can be a top-level view, or a subview.
This is very handy for printing out the elements of a relationship. A relationship is represented by a property that is itself a RelationalView. In our example, for each Person you might also want to print the person’s Interests. Inside the ForEach servlet bean, you have another call to a RelationalView that accesses the interests property of the row:
<table border> <tr><th>id</th><th>name</th><th>age</th></tr><tr>interests<> <dsp:droplet name="ForEach"> <dsp:param name="array" param="result"/> <dsp:oparam name="output"> <tr> <td><dsp:valueof param="element.id"/></td> <td><dsp:valueof param="element.name"/></td> <td><dsp:valueof param="element.age"/></td> <td> <dsp:droplet name="RelationalViewDroplet"> <dsp:param name="rview" param="element.interests"/> <dsp:oparam name="output"> <dsp:droplet name="ForEach"> <dsp:param name="array" param="result"/> <dsp:oparam name="output"> <dsp:valueof param="element.interest"/> </dsp:oparam> </dsp:droplet> </dsp:oparam> </dsp:droplet> </td> </tr> </dsp:oparam> </dsp:droplet> </table>
subviewName and subviewParam
Optionally, you can specify the name of the subview to display. If you specify this, then you must also specify rviewName. The parameters to the subview are placed in parameters named subviewParam0, subviewParam1, and so on. For example:
<dsp:droplet bean="RelationalViewDroplet">
<dsp:param name="rviewName" value="PersonRview"/>
<dsp:param name="subviewName" value="byId"/>
<dsp:param name="subviewParam0" param="personId"/>
Notice that the type restrictions on subviews still apply. For example, the byId expects a parameter of type int, which means that you cannot simply say:
<dsp:param name="subviewParam0" value="14"/>
Here a String value 14 is supplied, which causes a type error in the Relational Views system. To make this work, the desired ID must be stored as the int property of some object, or must be passed in as an int parameter. Then you can use the appropriate param: or property: to access the value.
operation
There are many forms of the select call, and this parameter determines which one is executed. This also determines what form the result parameter takes. The default value for operation is select:
select: callsselect(), and theresultparameter contains an array of the resulting rows.selectFirst: callsselectFirst(), and theresultparameter contains the single row (not an array of rows). If no row is returned, then theoutputparameter is not rendered.selectCount: callsselectCount(), and theresultparameter contains an Integer of the number of rows in the database.selectExists: callsselectExists, and theresultparameter contains a Boolean indicating if there are any rows in the subview.
firstRow
This parameter is only consulted if the operation is select (the default). This parameter indicates how many rows are to be skipped before starting the array results. If the parameter’s value is a String, it is converted to an integer.
rowCount
This parameter is only consulted if the operation is select (the default). This parameter indicates the maximum number of rows that are to be placed into the array of results.
functionName and functionParam
Instead of calling one of the operations on a RelationalView, you can invoke a query function by passing the function’s name in this parameter. The parameters to the function should be passed in parameters named functionParam0, functionParam1, and so on. As with the subviews, the values of these parameters must be of the correct types to be passed to the function. See subviewName and subviewParam, above. If you use this option, then the subview, operation, firstRow, and rowCount parameters are ignored.
resultName
Normally, the result of the RelationalView operation is placed into a parameter called result. You might want to change the name of this parameter. If so, you should set resultName to the name of the parameter where you want the results to be placed.
Output Parameters
result
The result of the RelationalView operation. If resultName is set, then the name that resultName is set to is used rather than result.
errorMessage
If an error occurs during the RelationalView operation, this parameter is set to the text of the corresponding error message.
Open Parameters
output
After the RelationalViewDroplet performs its operation and places the results in the result parameter (or whatever parameter is named by resultName), the RelationalViewDroplet renders the output parameter, giving it access to the results through the result parameter.
errorOutput
If an error occurs while the RelationalView is performing its operation, the servlet bean calls this parameter in place of the output parameter. The text of the error message is available in the errorMessage parameter.
Example
For example, this shows a .jsp page that obtains all of the rows from the PersonRview RelationalView, then uses the ForEach servlet bean to display each row in a table:
<dsp:importbean bean="/atg/dynamo/service/jdbc/RelationalViewDroplet"/> <dsp:importbean bean="/atg/dynamo/droplet/ForEach"/> <html> <head></head> <body> <dsp:droplet name="RelationalViewDroplet"> <dsp:param name="rviewName" value="PersonRview"/> <dsp:oparam name="output"> <table border> <tr><th>id</th><th>name</th><th>age</th></tr> <dsp:droplet name="ForEach"> <dsp:param name="array" param="result"/> <dsp:oparam name="output"> <tr> <td><dsp:valueof param="element.id"/></td> <td><dsp:valueof param="element.name"/></td> <td><dsp:valueof param="element.age"/></td> </tr> </dsp:oparam> </dsp:droplet> </table> </dsp:oparam> </dsp:droplet> </body> </html>
In this example, you are passing two parameters to the RelationalViewDroplet: rviewName and output. You give the name of the RelationalView to rviewName. The servlet bean calls select on that RelationalView, puts the array of rows into a parameter called result, then displays the output parameter. Our output parameter displays a table, then uses the ForEach servlet bean to run through each element of the result array, displaying one table row for each array element.
This is the basic way to use the RelationalViewDroplet. Set up the parameters to perform the desired query, then use the output parameter to display the results of the query.
