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 theresult
parameter contains an array of the resulting rows.selectFirst
: callsselectFirst()
, and theresult
parameter contains the single row (not an array of rows). If no row is returned, then theoutput
parameter is not rendered.selectCount
: callsselectCount()
, and theresult
parameter contains an Integer of the number of rows in the database.selectExists
: callsselectExists
, and theresult
parameter 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.